bmad-loop-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Module Setup

模块设置

Overview

概述

Installs, configures, and upgrades the bmad-loop module in a project.

This module is unusual: alongside its automation skills it relies on the bmad-loop orchestrator tool — the Python program that actually drives the loop — installed as the

bmad-loop

package from its public Git repository. The skills do nothing on their own.

The BMAD installer owns
_bmad/
registration; this skill does not. When bmad-loop is installed through the BMAD installer (

npx bmad-method install

), the installer stages the skills under

_bmad/bmad-loop/

, writes that module's own config and help files, records it in

_bmad/_config/

(manifest, skill manifest, files manifest), and rebuilds the

/bmad-help

catalog. It regenerates the central

_bmad/config.toml

on every run, so nothing outside the installer should write there.

So this skill's job is the part the installer structurally cannot do:

Install or upgrade the orchestrator tool (the installer copies skill directories only — it cannot carry a Python package).
Run
```
bmad-loop init
```
to register the per-CLI hooks, lay down the bundled skills, and write
```
.bmad-loop/policy.toml
```
+ gitignore entries.
Preflight with
```
bmad-loop validate
```
and point the user at per-role adapter config.

It also refreshes one file —

_bmad/bmad-loop/module-help.csv

— so the module's help entries are present even on a project that installed the tool directly rather than through the BMAD installer. Nothing else under

_bmad/

is written or deleted.

Module identity (name, code, version) comes from

./assets/module.yaml

{project-root}

is a literal token in BMAD config values — never substitute it there. This does not apply to the filesystem path arguments in the commands below: those are real paths, so resolve

{project-root}

to the actual project root before running.

在项目中安装、配置并升级 bmad-loop 模块。

该模块比较特殊：除了自动化 skills 之外，它还依赖 bmad-loop orchestrator 工具——即实际驱动 loop 的 Python 程序——该工具需要从其公开 Git 仓库以

bmad-loop

package 的形式安装。仅靠这些 skills 本身无法完成任何操作。

BMAD 安装器负责
_bmad/
注册；此 skill 不负责。通过 BMAD 安装器（

npx bmad-method install

）安装 bmad-loop 时，安装器会将 skills 暂存到

_bmad/bmad-loop/

，写入该模块自身的 config 和 help 文件，将其记录到

_bmad/_config/

（manifest、skill manifest、files manifest），并重新构建

/bmad-help

catalog。每次运行安装器时，它都会重新生成中央的

_bmad/config.toml

，因此安装器之外的任何内容都不应写入该文件。

因此，此 skill 负责的是安装器在结构上无法完成的部分：

安装或升级 orchestrator 工具（安装器只复制 skill 目录，无法携带 Python package）。
运行
```
bmad-loop init
```
以注册各 CLI hooks、部署内置 skills，并写入
```
.bmad-loop/policy.toml
```
及 gitignore 条目。
使用
```
bmad-loop validate
```
进行预检，并引导用户配置各角色的 adapter config。

它还会刷新一个文件——

_bmad/bmad-loop/module-help.csv

——以确保即使项目是直接安装工具而非通过 BMAD 安装器安装，模块的 help 条目仍然存在。

_bmad/

下的其他内容均不会被写入或删除。

模块标识（name、code、version）来自

./assets/module.yaml

。

{project-root}

是 BMAD config values 中的字面量 token——切勿在其中替换它。这不适用于以下命令中的文件系统路径 arguments：这些是真实路径，因此运行前应将

{project-root}

解析为实际的项目根目录。

On Activation

激活时执行的操作

Read
```
./assets/module.yaml
```
for module metadata (the
```
code
```
field is the module identifier).
Check whether
```
{project-root}/_bmad/
```
exists. If it does not, this project has no BMAD install — say so, and note that the automation skills expect one. Setup can still install the orchestrator tool.
Check whether
```
{project-root}/_bmad/bmad-loop/
```
exists. If it does, the module was installed by the BMAD installer and is already registered. If it does not, tell the user the module is not registered with BMAD, and that installing it via
```
npx bmad-method install
```
(selecting bmad-loop) adds it to
```
/bmad-help
```
. Do not gate setup on this — continue either way. On BMAD v7 the module installs with
```
bmad setup bmad-loop
```
instead (see bmad-loop's docs/setup-guide.md, "Installing on BMAD v7"), not the v6 installer.

Decide fresh-install vs upgrade. This drives whether the tool is upgraded and whether the per-project skills are refreshed. Treat it as an upgrade when either holds:

The user asked for one in their arguments —
```
upgrade
```
,
```
update
```
,
```
upgrade tool and skills
```
, or similar.
The orchestrator tool is already installed under uv: run
```
uv tool list
```
and look for a
```
bmad-loop
```
entry. (A bare
```
bmad-loop --version
```
is not sufficient on its own — it can be satisfied by a source checkout or unrelated virtualenv; see step 1 below.)

Otherwise it is a fresh install. State the decision to the user before proceeding — e.g. "Detected an existing bmad-loop install — running an upgrade: tool + skills" or "No existing install detected — running a fresh setup".

If the user provides arguments (e.g.

accept all defaults

--headless

upgrade

), use them and skip interactive prompting. Still display the full confirmation summary at the end.

读取
```
./assets/module.yaml
```
获取模块元数据（
```
code
```
字段是模块标识符）。
检查
```
{project-root}/_bmad/
```
是否存在。如果不存在，说明该项目未安装 BMAD，并指出自动化 skills 依赖 BMAD 安装。设置流程仍可安装 orchestrator 工具。
检查
```
{project-root}/_bmad/bmad-loop/
```
是否存在。如果存在，说明该模块已由 BMAD 安装器安装并完成注册。如果不存在，则告知用户该模块尚未注册到 BMAD，并说明通过
```
npx bmad-method install
```
安装并选择 bmad-loop 后，它会出现在
```
/bmad-help
```
中。不要因此阻止设置流程——无论是否存在都应继续。在 BMAD v7 上，应改用
```
bmad setup bmad-loop
```
安装模块（见 bmad-loop 的
```
docs/setup-guide.md
```
中“Installing on BMAD v7”一节），而不是使用 v6 安装器。

判断全新安装还是升级。 这将决定是否升级工具以及是否刷新项目级 skills。出现以下任一情况时，将其视为升级：

用户在参数中要求升级——例如
```
upgrade
```
、
```
update
```
、
```
upgrade tool and skills
```
或类似表述。
orchestrator 工具已通过 uv 安装：运行
```
uv tool list
```
并查找
```
bmad-loop
```
条目。（单独执行
```
bmad-loop --version
```
不足以确认这一点——它可能来自 source checkout 或无关的 virtualenv；参见下方步骤 1。）

否则即为全新安装。继续操作前应向用户说明判断结果——例如：“检测到已有 bmad-loop 安装——正在执行升级：工具 + skills”或“未检测到现有安装——正在执行全新设置”。

如果用户提供参数（例如

accept all defaults

、

--headless

、

upgrade

），使用这些参数并跳过交互式提示。仍在最后显示完整的确认摘要。

Register Help Entries

注册帮助条目

Refresh the module's help entries. This is the only file this skill writes under

_bmad/

, and it is exactly what the BMAD installer itself places there — so it is a no-op on an installer-installed project and idempotent on every re-run.

bash

mkdir -p "{project-root}/_bmad/bmad-loop"
cp ./assets/module-help.csv "{project-root}/_bmad/bmad-loop/module-help.csv"

/bmad-help

reads the assembled catalog at

_bmad/_config/bmad-help.csv

, which the BMAD installer rebuilds from every

_bmad/<module>/module-help.csv

. So on a project that never ran the BMAD installer, these entries become visible the next time it runs — not immediately. Say that plainly in the Confirm step rather than claiming the help system was updated.

Skip this step entirely if

{project-root}/_bmad/

does not exist.

刷新模块的 help 条目。这是此 skill 在

_bmad/

下唯一会写入的文件，且与 BMAD 安装器自身放置的文件完全相同——因此，对通过安装器安装的项目而言，此操作不会产生变化，并且每次重新运行都具备幂等性。

bash

mkdir -p "{project-root}/_bmad/bmad-loop"
cp ./assets/module-help.csv "{project-root}/_bmad/bmad-loop/module-help.csv"

/bmad-help

会读取

_bmad/_config/bmad-help.csv

中组装好的 catalog，而 BMAD 安装器会根据每个

_bmad/<module>/module-help.csv

重新构建该文件。因此，对于从未运行过 BMAD 安装器的项目，这些条目会在安装器下次运行时显示，而不是立即显示。应在 Confirm 步骤中明确说明这一点，不要声称帮助系统已经更新。

如果

{project-root}/_bmad/

不存在，则完全跳过此步骤。

Install the Orchestrator Tool

安装 Orchestrator 工具

The orchestrator is what spawns fresh coding CLI sessions through the selected adapter(s) to invoke

bmad-build-auto

(the upstream dev primitive;

bmad-dev-auto

on pre-rename releases) for the dev pass — then re-invokes it on the

done

spec for the follow-up review pass — and

bmad-loop-sweep

, watches their hook signals, and verifies their artifacts. Installing it is therefore part of setup, not an optional extra.

Why from Git? The BMAD installer copies only skill directories into a project — it does not carry sibling files, so the tool can't ride along in the skill folder. The canonical source is https://github.com/bmad-code-org/bmad-loop. (The reverse holds, though: the tool's wheel bundles the skills, so
bmad-loop init
lays them down into a project's skill trees on its own — see step 3.)

Unless the user explicitly asked to skip it (e.g.

skills only

--no-tool

), install or upgrade and bootstrap now. Resolve

{project-root}

to the real project path before running.

Check what's already on PATH: run
```
bmad-loop --version
```
. A version printing here does not mean this project is set up — it only means some
```
bmad-loop
```
is importable in the current environment. Before trusting it, run
```
uv tool list
```
and look for
```
bmad-loop
```
: if it's absent (the on-PATH copy comes from a source checkout or an unrelated virtualenv), warn the user that the active environment is shadowing a clean install and that the project would be relying on that checkout. Unless the user explicitly declines, install/upgrade from the canonical source below so the project doesn't depend on an incidental dev environment.
Install or upgrade from the Git repository (the
```
[tui]
```
extra pulls in the Textual dashboard so
```
bmad-loop tui
```
works).
```
uv tool install
```
puts
```
bmad-loop
```
in uv's own managed environment, so there's no PEP 668 externally-managed conflict and no need for
```
--user
```
, an activated virtualenv, or
```
--break-system-packages
```
.
- Fresh install (no uv-managed
```
bmad-loop
```
  ):
  bash
```
uv tool install "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git"
```
  Pin a release tag for reproducibility by appending
```
@v<X.Y.Z>
```
  to the Git URL.
- Upgrade (uv already manages
```
bmad-loop
```
  ):
  1. Record the current version first so you can report the delta:
    bmad-loop --version
    .
  2. Default — follow
    main
    (or the currently pinned tag):
    bash
```
uv tool upgrade bmad-loop --reinstall
```
    The
    --reinstall
    is required for a Git source: a plain
    uv tool upgrade
    reuses the cached commit and won't pull new code. Then offer to pin a release tag for reproducibility — if the user wants a specific version, move to it with:
    bash
```
uv tool install --force "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git@v<X.Y.Z>"
```
  3. Re-run
    bmad-loop --version
    and note the before → after for the confirmation step.
Bootstrap the project — install the coding-CLI hooks, the bundled
```
bmad-loop-*
```
skills, the
```
.bmad-loop/policy.toml
```
template, and the gitignore entry (idempotent).
First decide which coding CLI(s) the orchestrator should drive. The supported adapters are
```
claude
```
(default),
```
codex
```
,
```
gemini
```
,
```
copilot
```
, and
```
antigravity
```
(Google's
```
agy
```
). Hooks are registered per CLI, so the choice matters — register every CLI you intend to use for dev/review/triage. Ask the user (unless they already specified it in their setup args, e.g.
```
cli: claude, codex
```
, or accepted defaults — then default to
```
claude
```
only):
"Which coding CLI(s) should the orchestrator drive —
```
claude
```
,
```
codex
```
,
```
gemini
```
,
```
copilot
```
, and/or
```
antigravity
```
? You can pick more than one. [claude]"
Build the command with one
```
--cli <name>
```
per selected CLI (the flag is repeatable). On an upgrade, append
--force-skills
so the per-project skill copies are actually refreshed — without it
```
init
```
skips every existing skill dir and the project keeps stale skills against the upgraded tool. On a fresh install, omit it.
bash
```
# fresh install, claude only (default)
bmad-loop init --project "{project-root}" --cli claude

# fresh install, multiple, e.g. claude + codex + gemini
bmad-loop init --project "{project-root}" --cli claude --cli codex --cli gemini

# upgrade — refresh the bundled skills in place
bmad-loop init --project "{project-root}" --cli claude --force-skills
```
Names must be exactly
```
claude
```
,
```
codex
```
,
```
gemini
```
,
```
copilot
```
, or
```
antigravity
```
—
```
init
```
errors on an unknown profile and lists the valid ones.
```
init
```
prints any one-time first-run notes per CLI (e.g. start
```
claude
```
once in the project and accept the workspace-trust + hooks-approval dialogs before
```
bmad-loop run
```
— spawned sessions can't answer first-run dialogs). Relay those notes to the user.
Skills are installed automatically:
```
init
```
lays the bundled
```
bmad-loop-*
```
skills into the right tree for each selected CLI —
```
.claude/skills/
```
for
```
claude
```
,
```
.agents/skills/
```
for
```
codex
```
/
```
gemini
```
/
```
copilot
```
/
```
antigravity
```
. On a fresh install, existing skill dirs are left untouched; on an upgrade,
```
--force-skills
```
overwrites them with the bundled copies from the upgraded tool (use
```
--no-skills
```
to skip the step and manage skills yourself).
Note:
```
--force-skills
```
also overwrites
```
bmad-loop-setup
```
itself (it ships in the same bundle). That's expected and safe — the freshly laid-down setup skill takes effect on the next invocation, and your
```
_bmad/custom/*.toml
```
overrides (keyed by skill directory name) are untouched.
Preflight — verify config, sprint-status, git, tmux, and the coding CLI:
bash
```
bmad-loop validate --project "{project-root}"
```
```
validate
```
exits non-zero when the project isn't fully ready (e.g. no
```
sprint-status.yaml
```
yet, or
```
bmad-sprint-planning
```
hasn't run). On a fresh project that is expected — report its findings to the user as a readiness checklist, not as an install failure.
Point the user at per-role adapter config.
```
--cli
```
in step 3 only registers hooks for each CLI. Which CLI actually runs each stage is governed by
```
{project-root}/.bmad-loop/policy.toml
```
, written from a template by
```
init
```
. The
```
[adapter] name
```
(default
```
claude
```
) applies to every stage; optional
```
[adapter.dev]
```
,
```
[adapter.review]
```
, and
```
[adapter.triage]
```
tables override individual stages (each takes its own
```
name
```
,
```
model
```
,
```
effort
```
and
```
extra_args
```
). So a mixed setup — e.g.
```
claude
```
for dev,
```
codex
```
for review — needs both the hooks registered (step 3) and the role pointed at that CLI in
```
policy.toml
```
:
toml
```
[adapter]
name = "claude"        # default for all stages

[adapter.review]
name = "codex"         # review runs on codex instead
```
Tell the user where the file is and that any CLI named in
```
policy.toml
```
must also have been registered with
```
--cli
```
in step 3 (re-run
```
bmad-loop init --cli <name>
```
to add one later). Leave
```
policy.toml
```
untouched if they only use a single CLI — the default is correct.

orchestrator 会通过所选 adapter 启动全新的 coding CLI 会话，以调用

bmad-build-auto

（上游 dev primitive；在改名前的版本中为

bmad-dev-auto

）执行开发阶段——随后基于

done

spec 再次调用它，执行后续 review 阶段——并调用

bmad-loop-sweep

、监控它们的 hook 信号并验证产物。因此，安装 orchestrator 是设置的一部分，而不是可选的附加项。

为什么从 Git 安装？ BMAD 安装器只将 skill 目录复制到项目中——不会携带同级文件，因此该工具无法随 skill 文件夹一起安装。规范来源是 https://github.com/bmad-code-org/bmad-loop。（与此相反，工具的 wheel 会捆绑 skills，因此
bmad-loop init
本身可以将 skills 部署到项目的 skill 目录树中——参见步骤 3。）

除非用户明确要求跳过此步骤（例如

skills only

--no-tool

），否则现在立即执行安装或升级并完成初始化。运行前应将

{project-root}

解析为真实项目路径。

检查 PATH 上已有的内容：运行
bmad-loop --version
。这里打印出版本并不意味着项目已完成设置——它只表示当前环境中_某个_ bmad-loop 可导入。在信任它之前，运行
```
uv tool list
```
并查找
```
bmad-loop
```
：如果其中不存在（在 PATH 上的副本来自 source checkout 或无关的 virtualenv），则警告用户当前环境中的副本遮蔽了干净安装，项目将依赖那个 checkout。除非用户明确拒绝，否则从下面的规范来源执行安装或升级，避免项目依赖偶然的开发环境。
从 Git 仓库安装或升级（
```
[tui]
```
extra 会引入 Textual dashboard，使
```
bmad-loop tui
```
可以运行）。
```
uv tool install
```
会将
```
bmad-loop
```
放入 uv 自身管理的环境中，因此不存在 PEP 668 的 externally-managed 冲突，也不需要
```
--user
```
、激活 virtualenv 或
```
--break-system-packages
```
。
- 全新安装（没有由 uv 管理的
```
bmad-loop
```
  ）：
  bash
```
uv tool install "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git"
```
  为保证可复现性，可在 Git URL 后附加
```
@v<X.Y.Z>
```
  ，以固定 release tag。
- 升级（uv 已管理
```
bmad-loop
```
  ）：
  1. 首先记录当前版本，以便报告版本差异：
    bmad-loop --version
    。
  2. 默认情况下——跟随
    main
    （或当前固定的 tag）：
    bash
```
uv tool upgrade bmad-loop --reinstall
```
    对于 Git source，
    --reinstall
    是必需的：普通的
    uv tool upgrade
    会复用缓存的 commit，不会拉取新代码。随后提议固定 release tag以确保可复现性——如果用户需要特定版本，可使用以下命令切换：
    bash
```
uv tool install --force "bmad-loop[tui] @ git+https://github.com/bmad-code-org/bmad-loop.git@v<X.Y.Z>"
```
  3. 重新运行
    bmad-loop --version
    ，并在确认步骤中记录升级前 → 升级后的版本。
初始化项目——安装 coding-CLI hooks、内置的
```
bmad-loop-*
```
skills、
```
.bmad-loop/policy.toml
```
模板及 gitignore 条目（幂等）。
首先决定 orchestrator 应驱动哪些 coding CLI。受支持的 adapter 为
```
claude
```
（默认）、
```
codex
```
、
```
gemini
```
、
```
copilot
```
和
```
antigravity
```
（Google 的
```
agy
```
）。Hooks 按 CLI 注册，因此这一选择很重要——应注册所有计划用于 dev、review 或 triage 的 CLI。除非用户已在设置参数中指定（例如
```
cli: claude, codex
```
）或接受默认值，否则应询问用户；接受默认值时，仅使用
```
claude
```
：
“orchestrator 应驱动哪些 coding CLI——
```
claude
```
、
```
codex
```
、
```
gemini
```
、
```
copilot
```
和/或
```
antigravity
```
？可以选择多个。[claude]”
每个选定的 CLI 都在命令中添加一个
```
--cli <name>
```
（该参数可以重复）。升级时，追加
--force-skills
，确保项目级 skill 副本得到实际刷新——否则，
```
init
```
会跳过每个已有的 skill 目录，导致项目继续使用与升级后工具不匹配的旧 skills。全新安装时则省略此参数。
bash
```
# fresh install, claude only (default)
bmad-loop init --project "{project-root}" --cli claude

# fresh install, multiple, e.g. claude + codex + gemini
bmad-loop init --project "{project-root}" --cli claude --cli codex --cli gemini

# upgrade — refresh the bundled skills in place
bmad-loop init --project "{project-root}" --cli claude --force-skills
```
名称必须严格为
```
claude
```
、
```
codex
```
、
```
gemini
```
、
```
copilot
```
或
```
antigravity
```
——
```
init
```
遇到未知 profile 时会报错并列出有效选项。
```
init
```
会输出各 CLI 的一次性首次运行说明（例如，需要先在项目中启动一次
```
claude
```
，并接受 workspace-trust 和 hooks-approval 对话框，然后才能运行
```
bmad-loop run
```
——由工具启动的会话无法回答首次运行对话框）。应将这些说明传达给用户。
Skills 会自动安装：
```
init
```
会将内置的
```
bmad-loop-*
```
skills 部署到每个所选 CLI 对应的目录树——
```
claude
```
对应
```
.claude/skills/
```
，
```
codex
```
/
```
gemini
```
/
```
copilot
```
/
```
antigravity
```
对应
```
.agents/skills/
```
。全新安装时，已有 skill 目录保持不变；升级时，
```
--force-skills
```
会使用升级后工具内置的副本覆盖它们（可使用
```
--no-skills
```
跳过此步骤并自行管理 skills）。
注意：
```
--force-skills
```
也会覆盖
```
bmad-loop-setup
```
自身（它包含在同一 bundle 中）。这是预期行为且是安全的——新部署的 setup skill 会在下一次调用时生效，而你的
```
_bmad/custom/*.toml
```
overrides（以 skill 目录名为键）不会受到影响。
预检——验证 config、sprint-status、git、tmux 和 coding CLI：
bash
```
bmad-loop validate --project "{project-root}"
```
当项目尚未完全准备就绪时，
```
validate
```
会以非零状态退出（例如尚无
```
sprint-status.yaml
```
，或尚未运行
```
bmad-sprint-planning
```
）。在全新项目中，这是预期情况——应将检查结果作为就绪检查清单报告给用户，而不是将其视为安装失败。
**引导用户配置各角色的 adapter。**步骤 3 中的
```
--cli
```
只会为各 CLI 注册 hooks。实际运行各阶段的是哪个 CLI，则由
```
{project-root}/.bmad-loop/policy.toml
```
决定，该文件由
```
init
```
根据模板写入。
```
[adapter] name
```
（默认值为
```
claude
```
）适用于所有阶段；可选的
```
[adapter.dev]
```
、
```
[adapter.review]
```
和
```
[adapter.triage]
```
表可分别覆盖单个阶段（每个表都可设置自己的
```
name
```
、
```
model
```
、
```
effort
```
和
```
extra_args
```
）。因此，对于混合设置——例如使用
```
claude
```
执行 dev、使用
```
codex
```
执行 review——既需要注册 hooks（步骤 3），也需要在
```
policy.toml
```
中将对应角色指向该 CLI：
toml
```
[adapter]
name = "claude"        # default for all stages

[adapter.review]
name = "codex"         # review runs on codex instead
```
告知用户该文件的位置，并说明
```
policy.toml
```
中指定的每个 CLI 都必须已通过步骤 3 中的
```
--cli
```
注册（如需之后添加，可重新运行
```
bmad-loop init --cli <name>
```
）。如果用户只使用一个 CLI，则不要修改
```
policy.toml
```
——默认配置已经正确。

Confirm

确认

Report:

Fresh install: the installed
```
bmad-loop --version
```
, that
```
bmad-loop init
```
registered hooks, installed the
```
bmad-loop-*
```
skills, and wrote policy/gitignore for the selected coding CLI(s) (name each one — e.g. "hooks + skills installed for claude, codex").
Upgrade: the before → after
```
bmad-loop --version
```
(e.g. "upgraded 0.3.1 → 0.3.2", or "already current at 0.3.2"), and that the
```
bmad-loop-*
```
skills were refreshed (not skipped) with
```
--force-skills
```
in each CLI tree.

Also report:

The
```
bmad-loop validate
```
preflight result (pass, or the readiness checklist of what's still missing).
That
```
_bmad/bmad-loop/module-help.csv
```
was refreshed. If
```
_bmad/bmad-loop/
```
did not exist before this run (i.e. the BMAD installer never installed the module), say that the help entries will appear in
```
/bmad-help
```
after the BMAD installer next runs, and that installing the module via
```
npx bmad-method install
```
registers it properly (on BMAD v7,
```
bmad setup bmad-loop
```
instead).
That this skill wrote nothing else under
```
_bmad/
```
— module registration,
```
config.toml
```
, and the help catalog are owned by the BMAD installer.

Then display the

module_greeting

from

./assets/module.yaml

to the user.

报告：

**全新安装：**已安装的
```
bmad-loop --version
```
；
```
bmad-loop init
```
已注册 hooks、安装
```
bmad-loop-*
```
skills，并为所选的 coding CLI 写入 policy/gitignore（逐一列明，例如“已为 claude、codex 安装 hooks + skills”）。
升级：
```
bmad-loop --version
```
的升级前 → 升级后版本（例如“从 0.3.1 升级到 0.3.2”或“已是最新版本 0.3.2”），以及
```
bmad-loop-*
```
skills 已在每个 CLI 目录树中使用
```
--force-skills
```
完成刷新而非跳过。

还需报告：

```
bmad-loop validate
```
预检结果（通过，或列出仍缺失内容的就绪检查清单）。
```
_bmad/bmad-loop/module-help.csv
```
已刷新。如果本次运行前
```
{project-root}/_bmad/bmad-loop/
```
不存在（即 BMAD 安装器从未安装该模块），应说明帮助条目会在 BMAD 安装器下次运行后出现在
```
/bmad-help
```
中，并说明通过
```
npx bmad-method install
```
安装模块可完成正式注册（在 BMAD v7 上则使用
```
bmad setup bmad-loop
```
）。
此 skill 没有写入
```
_bmad/
```
下的其他任何内容——模块注册、
```
config.toml
```
和 help catalog 均由 BMAD 安装器负责。

然后向用户显示

./assets/module.yaml

中的

module_greeting

。

Outcome

后续处理

Use the user's configured name and language for the remainder of the session. Read them from BMAD's central config via its own resolver (four-layer TOML merge; needs BMAD v6.10+ and Python 3.11+):

bash

uv run "{project-root}/_bmad/scripts/resolve_config.py" --project-root "{project-root}" --key core

Take

user_name

and

communication_language

from the

core

table. If the script is absent or exits non-zero, fall back to addressing the user neutrally in English — do not write or repair any config file.

在本次会话余下部分，使用用户配置的 name 和 language。通过 BMAD 自身的 resolver 读取这些配置（四层 TOML 合并；需要 BMAD v6.10+ 和 Python 3.11+）：

bash

uv run "{project-root}/_bmad/scripts/resolve_config.py" --project-root "{project-root}" --key core

从

core

表中获取

user_name

和

communication_language

。如果脚本不存在或以非零状态退出，则改用中性英文称呼用户——不要写入或修复任何配置文件。