swain-init

项目初始化

在项目中采用 swain 的一次性设置。此技能不可幂等——它会迁移文件并安装工具。要进行每个会话的健康检查，请使用 swain-doctor。

预检

在任何阶段开始前，运行预检脚本以收集环境状态。此单次调用会替代所有内联检查代码块——以下各阶段会读取 JSON 输出，而不是运行 shell 命令。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
PREFLIGHT_SCRIPT="$(find "$REPO_ROOT" -path '*/swain-init/scripts/swain-init-preflight.sh' -print -quit 2>/dev/null)"
PREFLIGHT_JSON=$( bash "$PREFLIGHT_SCRIPT" --repo-root "$REPO_ROOT" 2>/dev/null )
echo "$PREFLIGHT_JSON"

保存 PREFLIGHT_JSON，供以下所有阶段使用。每项决策都应引用此 JSON 中的字段——除非要执行变更，否则不要运行其他检查命令。

阶段 0：检测是否已初始化

从预检 JSON 中读取 marker.action。

• "delegate" — 主版本相同。告诉用户：

  项目已初始化（swain marker.release_version，初始化版本 vmarker.last_version）。正在委派给 swain-session。

  跳转到下方的阶段 7（会话开始）。不要运行阶段 1–6。

• "upgrade" — 有更新的主版本可用。告诉用户：

  项目使用 swain marker.last_release_version 初始化（初始化版本 vmarker.last_version）。当前版本：marker.release_version（初始化版本 vmarker.current_version）。建议运行 /swain update 以获取新功能。 正在开始会话。

  跳转到下方的阶段 7（会话开始）。不要重新运行初始化流程——升级由 swain-update 处理，而非 swain-init。

• "onboard" — 未找到标记。继续执行完整的初始化流程（阶段 1–6）。

阶段 1：将 CLAUDE.md 迁移为 AGENTS.md

目标：采用 @AGENTS.md 引入模式，让项目说明存放在 AGENTS.md 中（Claude Code、GitHub 以及其他原生读取 AGENTS.md 的工具均可使用）。

从预检 JSON 中读取 migration.state。

如果是 "fresh"

创建两个文件：

• CLAUDE.md： @AGENTS.md
• AGENTS.md： # AGENTS.md（空文件——治理规则将在阶段 5 添加）

如果是 "migrated"

跳转到阶段 2。

如果是 "standard"

1. 将 CLAUDE.md 的内容复制到 AGENTS.md（保留所有内容）。
2. 如果 CLAUDE.md 包含 `` 块，则从 AGENTS.md 副本中移除该块——将在阶段 5 重新添加干净版本。
3. 将 CLAUDE.md 替换为 @AGENTS.md。

告诉用户：

已将 CLAUDE.md 的内容迁移到 AGENTS.md，并将 CLAUDE.md 替换为 @AGENTS.md。你现有的说明均已保留——Claude Code 会通过引入指令读取 AGENTS.md。

如果是 "split"

两个文件都包含内容。询问用户：

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 的内容（不含任何 `` 块）追加到 AGENTS.md，并将 CLAUDE.md 替换为 @AGENTS.md。

阶段 2：验证依赖项

步骤 2.1 — uv

从预检 JSON 中读取 uv.available。

如果为 false，则安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

如果安装失败，告诉用户：

uv 安装失败。你可以手动安装（https://docs.astral.sh/uv/getting-started/installation/）——swain 脚本需要 uv 来运行 Python。

安装失败时跳过阶段 2 的其余部分（不要因此阻止初始化，但需提醒用户，没有 uv 脚本将无法运行）。

步骤 2.2 — 随附的 tk

从预检 JSON 中读取 tk.path 和 tk.healthy。

如果 tk.path 为 null 或 tk.healthy 为 false，告诉用户：

未找到随附的 tk 脚本，或该脚本已损坏。这通常意味着 swain-do 技能未完整安装。尝试运行 /swain update 以重新安装技能。

步骤 2.3 — 从 beads 迁移（如适用）

读取预检 JSON 中的 beads.exists 和 beads.has_backup。

如果 beads.exists 和 beads.has_backup 均为 true，提供迁移选项：

找到现有的 .beads/ 数据。要将任务迁移到 tk 吗？ 这会将 .beads/backup/issues.jsonl 转换为 .tickets/ Markdown 文件。

如果用户同意，运行迁移：

TK_BIN="$(cd "$(dirname "$(find . .claude .agents -path '*/swain-do/bin/tk' -print -quit 2>/dev/null)")" && pwd)"
export PATH="$TK_BIN:$PATH"
cp .beads/backup/issues.jsonl .beads/issues.jsonl 2>/dev/null
ticket-migrate-beads
ls .tickets/*.md 2>/dev/null | wc -l

告知用户迁移结果，并说明验证完成后可以删除 .beads/。

如果 beads.exists 为 false，则跳过。tk 会在首次运行 tk create 时创建 .tickets/。

步骤 2.4 — Operator bin/ 符号链接（SPEC-214、ADR-019）

从预检 JSON 中读取 bin_manifests。为每个条目创建 bin/ 符号链接：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
BIN_DIR="$REPO_ROOT/bin"
SKILLS_ROOT="$REPO_ROOT/.agents/skills"
for manifest_dir in "$SKILLS_ROOT"/*/usr/bin; do
  [ -d "$manifest_dir" ] || continue
  for entry in "$manifest_dir"/*; do
    [ -e "$entry" ] || [ -L "$entry" ] || continue
    cmd_name="$(basename "$entry")"
    script_path="$(cd "$manifest_dir" && readlink -f "$cmd_name" 2>/dev/null || true)"
    [ -z "$script_path" ] || [ ! -f "$script_path" ] && continue
    rel_path="$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1], sys.argv[2]))" "$script_path" "$BIN_DIR" 2>/dev/null || echo "")"
    [ -z "$rel_path" ] && continue
    if [ -L "$BIN_DIR/$cmd_name" ]; then
      echo "already linked: $cmd_name"
    elif [ -e "$BIN_DIR/$cmd_name" ]; then
      echo "conflict — bin/$cmd_name exists as a real file; skipping"
    else
      mkdir -p "$BIN_DIR"
      ln -sf "$rel_path" "$BIN_DIR/$cmd_name"
      echo "created bin/$cmd_name"
    fi
  done
done

告知用户现在哪些 operator 命令可在 bin/ 中使用。

如果 bin_manifests 为空，则静默跳过。

阶段 3：Pre-commit 安全钩子

目标：配置用于扫描密钥的 pre-commit 钩子，以便在凭据进入 git 历史记录前将其捕获。默认扫描器为 gitleaks；其他扫描器（TruffleHog、Trivy、OSV-Scanner）需选择启用。

步骤 3.1 — 检查现有配置

从预检 JSON 中读取 precommit.config_exists。

如果为 true： 显示当前 .pre-commit-config.yaml 的内容并询问：

找到现有的 .pre-commit-config.yaml。要如何处理？

1. 合并 — 在现有钩子旁添加 swain 的 gitleaks 钩子
2. 跳过 — 保持 pre-commit 配置不变
3. 替换 — 覆盖为 swain 的默认配置（现有钩子将会丢失）

如果用户选择跳过，则跳至阶段 4。

如果为 false： 继续执行步骤 3.2。

步骤 3.2 — 安装 pre-commit 框架

从预检 JSON 中读取 precommit.framework。

如果为 false，则安装：

uv tool install pre-commit

如果 uv 不可用或安装失败，发出警告：

pre-commit 框架不可用。你可以手动安装（uv tool install pre-commit 或 pip install pre-commit）。跳过钩子设置。

如果无法安装 pre-commit，则跳至阶段 4。

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

默认配置会启用 gitleaks：

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks

如果用户要求启用其他扫描器（通过 --scanner 标志或在询问时提出），则添加相应的钩子：

TruffleHog（选择启用）：

  - repo: https://github.com/trufflesecurity/trufflehog
    rev: v3.88.1
    hooks:
      - id: trufflehog
        args: ['--results=verified,unknown']

Trivy（选择启用）：

  - 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（选择启用）：

  - repo: https://github.com/nicjohnson145/pre-commit-osv-scanner
    rev: v0.0.1
    hooks:
      - id: osv-scanner

写入配置文件。如果与现有配置合并，则将新的仓库条目追加到现有的 repos: 列表中。

步骤 3.4 — 安装钩子

运行 pre-commit install 以激活钩子。

步骤 3.5 — 更新 swain.settings.json

读取现有的 swain.settings.json（如果有），并添加 sync.scanners 键：

{
  "sync": {
    "scanners": {
      "gitleaks": { "enabled": true },
      "trufflehog": { "enabled": false },
      "trivy": { "enabled": false, "scanners": ["vuln", "license"], "severity": "HIGH,CRITICAL" },
      "osv-scanner": { "enabled": false }
    }
  }
}

对于用户选择启用的扫描器，将 enabled: true 设为 true。与现有设置合并，不要覆盖其他键。

告知用户：

已配置使用 gitleaks（默认）的 Pre-commit 钩子。扫描器设置已保存到 swain.settings.json。如要稍后启用其他扫描器，请编辑 swain.settings.json 并重新运行 /swain-init。

阶段 4：Superpowers 配套工具

目标：如果尚未安装 obra/superpowers，则提供安装选项。

步骤 4.1 — 检测 superpowers

从预检 JSON 中读取 superpowers.installed。

如果为 true，则报告“Superpowers：已安装”，并跳至阶段 4.4。

步骤 4.2 — 提供安装选项

询问用户：

尚未安装 Superpowers（obra/superpowers）。它提供 TDD、头脑风暴、计划编写和验证技能，swain 会在实现和设计工作中串联使用这些技能。

现在安装 superpowers 吗？（yes/no）

如果用户回答 no，则注明“Superpowers：已跳过”，并继续至阶段 4.4。用户随时可以稍后安装：npx skills add obra/superpowers。

步骤 4.3 — 安装

npx skills add obra/superpowers

如果安装成功，告知用户：

Superpowers 已安装。现在可以使用头脑风暴、TDD、计划编写和验证技能。

如果安装失败，发出警告：

Superpowers 安装失败。你可以手动重试：npx skills add obra/superpowers

无论结果如何，都继续至阶段 4.4。

步骤 4.4 — Tmux

读取预检 JSON 中的 tmux.installed。

如果为 true，报告“tmux：已安装”，并继续执行阶段 4.5。

如果为 false，询问用户：

未安装 tmux。swain 在可用时会使用 tmux 来命名标签页。它是可选的——没有它，swain 仍可运行，但会话标签页命名功能将不可用。

现在安装 tmux？（是/否）

如果选择是：

brew install tmux

如果安装成功，告知用户：

tmux 已安装。工作区布局和标签页命名功能现已可用。

如果安装失败，警告：

tmux 安装失败。你可以手动安装：brew install tmux

如果选择否，记下“tmux：已跳过”，并继续执行阶段 4.5。

阶段 4.5：Shell 启动器

目标：提供安装 swain shell 函数的选项，让用户只需运行一条命令即可启动 swain。模板按运行时和 shell 存储在 templates/launchers/{runtime}/swain.{shell} 中（相对于此技能目录）——请检查模板，了解将添加的具体内容。支持的运行时定义在 ADR-017 中。

步骤 4.5.1 — 检测 shell

读取预检 JSON 中的 launcher.shell。

支持的 shell：zsh、bash、fish。如果 shell 不在此列表中，告知用户：

zsh、bash 和 fish 均有可用的 Shell 启动器模板。暂不支持你的 shell（launcher.shell）——跳过启动器设置。

跳至阶段 5。

步骤 4.5.2 — 检查是否已有启动器

读取预检 JSON 中的 launcher.already_installed。

如果为 true，报告“Shell 启动器：已安装”，并跳至阶段 5。不要修改现有函数。

步骤 4.5.3 — 检测运行时

读取预检 JSON 中的 launcher.runtimes。

如果数组为空，告知用户：

未找到受支持的 Agent CLI 运行时（已检查：claude、gemini、codex、copilot、crush）。请先安装其中一个，然后重新运行 /swain-init。

跳至阶段 5。

步骤 4.5.4 — 选择运行时

• 找到一个运行时： 直接提供该运行时。
• 找到多个运行时： 列出编号选项，并询问用户要使用哪一个。如果有 claude，则默认选择它。

读取预检 JSON 中的 launcher.template_dir。构造模板路径：

$TEMPLATE_DIR/$SELECTED_RUNTIME/swain.$SHELL_NAME

步骤 4.5.5 — 显示模板并提供安装选项

读取模板文件内容，并向用户展示：

Shell 启动器 — 要在你的 shell 中添加 swain 命令吗？

检测到的运行时：[运行时名称]。以下内容将添加到 <rc-file>：

<template content>

安装？（是/否）

对于 Crush 模板，添加备注：“Crush 仅部分支持——它无法接受初始提示，因此会话初始化依赖 AGENTS.md 自动调用指令。”

步骤 4.5.6 — 安装

如果用户同意，将模板内容追加到 rc 文件中（从预检 JSON 读取 launcher.rc_file，例如 cat "$TEMPLATE_FILE" >> "$RC_FILE"）。

告知用户：

Shell 启动器已安装。运行 source <rc-file>（或重启 shell）即可启用 swain 命令。

如果用户拒绝，记下“Shell 启动器：已跳过”，并继续执行阶段 5。

阶段 5：Swain 治理

目标：将 swain 的路由和治理规则添加到 AGENTS.md。

步骤 5.1 — 检查是否已有治理规则

读取预检 JSON 中的 governance.installed。

如果为 true，表示治理规则已安装。告知用户，并跳至阶段 5.5。

步骤 5.2 — 征求许可

询问用户：

准备将 swain 治理规则添加到 AGENTS.md。这些规则将：

• 将制品请求（规范、故事、ADR 等）路由到 swain-design
• 将任务跟踪路由到 swain-do（使用 tk）
• 强制执行实现前流程（先制定计划，再编写代码）
• 优先使用 swain 技能，而非内置替代方案

将治理规则添加到 AGENTS.md？（是/否）

如果选择否，跳至阶段 5.5。

步骤 5.3 — 注入治理规则

从 swain-doctor/references/AGENTS.content.md 中读取规范治理内容（在 .claude/skills、.agents/skills 和 skills 目录中搜索该文件）。将该文件的完整内容追加到 AGENTS.md。

告诉用户：

已将治理规则添加到 AGENTS.md。这些规则可确保 swain 技能能够正确路由，并强制执行约定。你可以自定义 `` 标记之外的任何内容。

阶段 5.5：README 撰写与工件提案（SPEC-207）

目标：确保每个 swain 项目都有 README，并在工件树为空时提议根据 README 初始化工件。

步骤 5.5.1 — 检查 README

从预检 JSON 中读取 readme.exists。

步骤 5.5.2 — 缺少 README 时创建

如果 readme.exists 为 false，则使用预检 JSON 中的 readme.has_code 和 readme.has_artifacts 确定项目背景：

• 没有代码，也没有工件 — 询问操作者：“这个项目是做什么的？”根据他们的回答编写 README。
• 有代码，没有工件 — 从代码中推断项目用途（阅读入口点、package.json/pyproject.toml/go.mod 等）。向操作者提交 README 草稿供其编辑。
• 有工件，没有 README — 根据 Active Visions、Designs、Journeys 和 Personas 汇编内容。向操作者提交草稿供其编辑。

向操作者提交草稿。他们可以批准、编辑或跳过。如果他们跳过，则在摘要中注明“README：已跳过”，swain-doctor 会在后续会话中标记此项。

步骤 5.5.3 — 根据 README 提议种子工件

从预检 JSON 中读取 readme.active_count。

如果 readme.active_count < 3 且 README.md 存在，则读取 README 并通过语义分析提取意图声明。提议创建种子工件：

• 愿景 — 根据 README 对项目功能及其目的的描述。
• 用户画像 — 根据 README 面向的对象及其描述的问题。
• 用户旅程 — 根据使用流程、示例或“快速入门”路径。
• 设计 — 根据架构或结构方面的声明。

逐一提交每个提案。操作者可以批准、编辑或拒绝。已批准的工件通过 swain-design 创建。被拒绝的提案会直接丢弃，不作提示。

**语义提取：**将整份 README 作为散文阅读。不使用基于约定的章节，也不使用操作者放置的标记。README 中的任何声明都可能是意图来源——包括安装说明、功能描述、行为声明和架构陈述。

阶段 6：完成

步骤 6.1 — 创建 .agents 目录

如果 .agents/ 不存在，则创建该目录（mkdir -p .agents）。该目录供 swain-do 存储配置，并供 swain-design 脚本存储日志。

步骤 6.1.1 — 初始化 .agents/bin/（ADR-019）

创建 .agents/bin/，并为技能树中所有面向 Agent 的脚本创建符号链接：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
AGENTS_BIN="$REPO_ROOT/.agents/bin"
SKILLS_ROOT="$REPO_ROOT/.agents/skills"
mkdir -p "$AGENTS_BIN"
OPERATOR_SCRIPTS="swain swain-box"
for skill_scripts_dir in "$SKILLS_ROOT"/*/scripts; do
  [ -d "$skill_scripts_dir" ] || continue
  for script in "$skill_scripts_dir"/*; do
    [ -f "$script" ] && [ -x "$script" ] || continue
    script_name="$(basename "$script")"
    case "$script_name" in test-*) continue ;; esac
    echo " $OPERATOR_SCRIPTS " | grep -q " $script_name " && continue
    rel_path="$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1], sys.argv[2]))" "$script" "$AGENTS_BIN" 2>/dev/null)" || continue
    ln -sf "$rel_path" "$AGENTS_BIN/$script_name"
  done
done

如果 .gitignore 中尚未包含 .agents/bin/ 和 .agents/session.json，则将它们添加进去（使用方项目不应跟踪这些内容）。

步骤 6.2 — 运行 swain-doctor

调用 swain-doctor 技能。该技能会验证 .tickets/ 的健康状况、检查过期锁、移除旧版技能目录，并确保治理规则已正确安装。

步骤 6.3 — 入门引导

以入门模式调用 swain-help 技能，为用户引导介绍刚刚安装的内容。

步骤 6.4 — 写入 .swain/init.json 标记文件

所有入门阶段完成后，写入 .swain/init.json 标记文件。从预检 JSON 中读取 marker.current_version 作为技能版本，并读取 marker.release_version 作为发行版本。

如果 .swain/init.json 已存在（部分重新初始化），则读取该文件并向历史数组追加内容。否则，创建新文件：

{
  "history": [
    {
      "version": "4.0.0",
      "release": "v0.29.0-alpha",
      "timestamp": "2026-03-26T18:30:00Z",
      "action": "init"
    }
  ]
}

对于升级（供 swain-update 将来使用），则追加一条 "action": "upgrade" 的记录。

写入文件，并确保 .gitignore 中包含 .swain/（这是项目本地状态，不共享）。

Step 6.5 — 总结

报告已完成的事项：

swain init 已完成。

• CLAUDE.md → @AGENTS.md 引入模式：[已完成/已跳过/已设置]
• tk（工单）已验证：[已完成/未找到]
• Beads 迁移：[已完成/已跳过/未找到 beads]
• 提交前安全钩子：[已完成/已跳过/已配置]
• Superpowers：[已安装/已跳过/已存在]
• tmux：[已安装/已跳过/已存在]
• Shell 启动器：[已安装（运行时）/已跳过/已存在/未找到运行时/不支持的 shell]
• AGENTS.md 中的 Swain 治理：[已完成/已跳过/已存在]
• README：[已初始化/已存在/已跳过]
• README 中的工件提案：[提出 N 项，接受 M 项/已跳过/不适用]
• 初始化标记：已写入（.swain/init.json）

Step 6.6 — 开始会话

成功完成引导后，继续执行下文的 Phase 7（会话开始）。

Phase 7: 会话开始（ADR-023）

此阶段每次都会运行——包括全新引导之后（Phase 6）以及已初始化的快速路径（Phase 0）。它取代了之前的 swain-session 启动序列。

Step 7.1 — 快速问候

运行快速问候脚本。它会在内部为所有只读状态调用会话预检，然后执行轻量级变更（标签命名、锁清理）。不会串联子进程——只执行一次预检。

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-greeting.sh" --json

问候会输出结构化 JSON：

{
  "greeting": true,
  "branch": "trunk",
  "dirty": false,
  "isolated": false,
  "bookmark": "Left off implementing the bootstrap script",
  "focus": "VISION-001",
  "tab": "project @ branch",
  "warnings": []
}

会话预检（由问候在内部调用）还会收集上次会话的状态。若要直接访问：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
PREFLIGHT_JSON=$( bash "$REPO_ROOT/.agents/bin/swain-session-preflight.sh" --repo-root "$REPO_ROOT" 2>/dev/null )

收到问候 JSON 后：

1. 向操作员展示问候信息——分支、脏状态、书签（如果有）、焦点领域（如果有）和警告。

2. 如果 bookmark 不为 null，显示：

   正在恢复会话 — 上次：{bookmark}

3. 如果 isolated 为 false，现在不要创建工作树——工作树创建延迟到 swain-do 任务分派时执行（SPEC-195）。

如果未设置 $TMUX（通过 JSON 中缺少 tab 检测），检查是否已安装 tmux：

• 未安装 tmux： 提供安装选项（brew install tmux）。
• 已安装 tmux 但不在会话中： 显示：[note] 不在 tmux 会话中 — 会话标签和窗格功能不可用

Step 7.2 — 初始化会话状态

从会话预检 JSON 中读取 prev_session（如果问候未提供，则直接调用预检）。如果 prev_session.exists 为 true，显示其焦点领域、离场备注和决策数量。询问操作员：“继续上次会话还是开始新会话？”

如果开始新会话（或没有上次会话）：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-state.sh" init \
  --focus "<FOCUS-ID>" \
  --session-roadmap "$(pwd)/SESSION-ROADMAP.md" \
  --repo-root "$REPO_ROOT"

Step 7.3 — 焦点领域

焦点领域将建议限定在单一愿景或计划范围内。操作员决定要处理的事项时设置焦点领域。

如果问候 JSON 包含 focus 值： 向操作员确认：

焦点领域：{focus}。继续使用此焦点，还是更改？

如果未设置焦点： 询问操作员想要处理什么。将名称解析为工件 ID：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/chart.sh" --ids --flat 2>/dev/null | grep -i "<name>"

如果恰好有一个匹配项，则使用它。如果有多个匹配项，请操作员澄清。如果没有匹配项，告知操作员并提供创建选项。

设置焦点：

bash "$REPO_ROOT/.agents/bin/swain-focus.sh" set <RESOLVED-ID>

显示焦点工件上下文：

bash "$REPO_ROOT/.agents/bin/artifact-context.sh" <RESOLVED-ID> 2>/dev/null

焦点领域存储在 .agents/session.json 的 focus_lane 键下，并会在整个会话期间保持有效。

步骤 7.4 — 会话用途文本

当操作员使用自由文本启动时（例如，swain new bug about timestamps），启动器会导出 SWAIN_PURPOSE，并且对于接受初始提示词的运行时，还会以内联方式传入 /swain-init Session purpose: new bug about timestamps。

问候脚本（swain-session-greeting.sh）读取 $SWAIN_PURPOSE 并确定性地写入书签（SPEC-297）。问候 JSON 中的 purpose 字段会展示捕获的文本。

当问候 JSON 的 purpose 字段不为 null 时：

• 向操作员显示：**Session purpose:** <text>。

不要重新解析初始提示词，也不要自行调用 swain-bookmark.sh——问候脚本已经完成了这两项操作。内联提示词文本仅用于显示上下文；环境变量才是唯一可信来源。

工作树 / 分支变更

当 Agent 进入工作树或切换分支时，使用 --path 重新运行引导程序以更新标签页名称：

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-bootstrap.sh" --path "$NEW_WORKDIR" --skip-worktree --auto

重新运行 init

如果用户在已完成设置的项目上运行 /swain-init，阶段 0 会读取预检 JSON 的 marker.action 字段，并跳转到阶段 7（会话开始）——不会运行任何引导阶段，也不会出现交互式提示。这样用户就能养成将 /swain-init 作为单一入口的习惯。

若要强制重新进行引导，请删除 .swain/init.json 并重新运行。