blueprint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/blueprint

Write a blueprint (plan file) for the current task. Requires /orient to have run first.

为当前任务编写蓝图（计划文件）。要求先执行/orient步骤。

Sequence

执行流程

Check prerequisites. Confirm a worktree exists and /orient has identified the task. If not, stop and tell the user.
Brainstorm (one round). Invoke
```
/brainstorming
```
with the task description. One round only — capture direction, do not iterate.
Read the template. Read
```
ai-workspace/plans/TEMPLATE.md
```
from the repo root.
Write the plan. Create
```
ai-workspace/plans/<branch-slug>.md
```
with ALL template fields:

Field	How to fill
Branch	Current branch name
Target	Branch to merge into. Default: detected via reflog parent (see below), falling back to `main` . Override only when intentionally retargeting. `/ship` reads this field.
Created	Today's date (YYYY-MM-DD)
Status	`In Progress`
Threat model	See selection table below
Scope ceiling	Keep template defaults (400/6 soft, 800/10 hard)
Task	1-3 sentences: what and why
Steps	Checkbox list of concrete implementation steps
Confidence Scaffold	Required for `adversarial` . Recommended for complex `advisory` .
Outcomes & Learnings	Leave empty — populated by /archive

Commit the plan. Stage and commit the plan file before handing off to
```
/review
```
:
bash
```
git -C "$WORKTREE" add ai-workspace/plans/<name>.md
git -C "$WORKTREE" commit -m "blueprint: <name>"
```
Required because
```
/review
```
works against committed state. A session crash or
```
/clear
```
after writing the plan but before
```
/review
```
runs loses the brainstorming work otherwise. See ADR-008 (
```
refs/wip/checkpoints/<branch>
```
Stop-hook backstop) for the recovery path if this step is skipped.

检查前置条件：确认工作树已存在且/orient已识别任务。若未满足，停止操作并告知用户。
头脑风暴（一轮）：根据任务描述调用
```
/brainstorming
```
。仅进行一轮——明确方向即可，无需迭代。
读取模板：从仓库根目录读取
```
ai-workspace/plans/TEMPLATE.md
```
文件。
编写计划：创建
```
ai-workspace/plans/<branch-slug>.md
```
文件，填充所有模板字段：

字段	填充方式
Branch（分支）	当前分支名称
Target（目标分支）	要合并到的分支。默认值：通过引用日志父节点检测（见下文），若检测失败则回退为 `main` 。仅当有意重新指定目标时才覆盖此值。 `/ship` 会读取此字段。
Created（创建日期）	今日日期（YYYY-MM-DD格式）
Status（状态）	`In Progress`
Threat model（威胁模型）	见下方选择表
Scope ceiling（范围上限）	保留模板默认值（软限制400/6，硬限制800/10）
Task（任务）	1-3句话：说明任务内容及目的
Steps（步骤）	具体实施步骤的复选框列表
Confidence Scaffold（置信框架）	`adversarial` 类型必填。复杂的 `advisory` 类型推荐填写。
Outcomes & Learnings（成果与心得）	留空——由/archive步骤填充

提交计划：在移交至
```
/review
```
前，暂存并提交计划文件：
bash
```
git -C "$WORKTREE" add ai-workspace/plans/<name>.md
git -C "$WORKTREE" commit -m "blueprint: <name>"
```
此步骤为必填项，因为
```
/review
```
基于已提交状态工作。若在编写计划后、
```
/review
```
运行前出现会话崩溃或执行
```
/clear
```
，未提交的头脑风暴成果将会丢失。若跳过此步骤，可参考ADR-008（
```
refs/wip/checkpoints/<branch>
```
停止钩子备份）进行恢复。

Detecting the Target

检测目标分支

The default Target is the branch this branch was cut from, read from the reflog:

bash

TARGET=$(
  git reflog show HEAD --pretty=format:'%gs' \
    | grep "^branch: Created from" \
    | head -1 \
    | sed 's/branch: Created from //' \
    | sed 's|^origin/||'
)
TARGET=${TARGET:-main}

Falls back to

main

when the reflog is empty (web sessions, detached-HEAD creation). Use this whenever the user hasn't explicitly named a Target. Pure git — works in any environment without tool installs.

默认目标分支为当前分支的源分支，从引用日志中读取：

bash

TARGET=$(
  git reflog show HEAD --pretty=format:'%gs' \
    | grep "^branch: Created from" \
    | head -1 \
    | sed 's/branch: Created from //' \
    | sed 's|^origin/||'
)
TARGET=${TARGET:-main}

当引用日志为空时（如Web会话、分离HEAD状态创建的分支），回退为

main

。除非用户明确指定目标分支，否则均使用此方法。纯Git实现——无需安装额外工具，可在任意环境中运行。

Threat model selection

威胁模型选择

Signal	Model
Internal tooling, refactor, docs, tests, config	`advisory`
Auth, secrets, input validation, CI, hooks, permissions	`adversarial`
Unsure	`adversarial`

信号	模型
内部工具、重构、文档、测试、配置	`advisory`
认证、密钥、输入验证、CI、钩子、权限	`adversarial`
不确定	`adversarial`

Guardrails

约束规则

Do NOT review the blueprint. That is /review (Step 4).
Do NOT start implementation. The blueprint is the deliverable.
Do NOT skip any template field.
Do NOT proceed to
```
/review
```
without committing the blueprint file first.
If brainstorming reveals the task is one-sentence scope, say so and skip.
Scope ceiling values are fixed — do not change them.
Steps must be concrete actions with checkboxes, not vague phases.
Include test steps explicitly. When tests need a separate author (TDD contract), list them as distinct tasks from implementation so /build dispatches test-writer and implementer separately.

不得评审蓝图。评审为/review（第4步）的职责。
不得开始实施。蓝图即为交付物。
不得跳过任何模板字段。
未提交蓝图文件前，不得进入
```
/review
```
步骤。
若头脑风暴发现任务范围仅为一句话，需告知用户并跳过此步骤。
范围上限值为固定值——不得修改。
步骤必须是带复选框的具体操作，而非模糊阶段。
需明确包含测试步骤。当测试需要单独编写（TDD契约）时，需将其列为与实施分离的独立任务，以便/build步骤分别分派测试编写者和实施者。

Output

输出

After writing, report:

Plan written: ai-workspace/plans/<name>.md
Threat model: advisory|adversarial
Steps: <count>
Next step: /review (Step 4)

编写完成后，输出如下内容：

计划已生成：ai-workspace/plans/<name>.md
威胁模型：adversarial|advisory
步骤数量：<count>
下一步：/review（第4步）