| name | trellis-brainstorm |
| description | 实现前引导协作式需求发现。创建 task 目录、初始化 PRD、一次提出一个高价值问题、研究技术选择，并收敛到 MVP scope。当需求不清晰、存在多种有效方案，或用户描述新功能/复杂 task 时使用。 |
Brainstorm - 需求发现（AI Coding 增强）
CoreRule：持续追问此计划的每个方面，直到我们达成共同理解。沿着 design tree 的每个分支推进，逐一解决决策之间的依赖。对每个问题，都提供你的推荐答案。
一次只问一个问题。
如果某个问题可以通过探索 codebase 回答，就改为探索 codebase。
在实现前引导 AI 进行协作式需求发现，并针对 AI coding workflows 优化：
- Task-first（立即捕获想法）
- Action-before-asking（减少低价值问题）
- 技术选择 Research-first（避免要求用户发明选项）
- Diverge → Converge（扩展思考，然后锁定 MVP）
使用时机
当用户描述开发 task 时，由 start（Trellis command）触发，尤其适用于：
- requirements 不清晰或仍在演化
- 存在多条有效 implementation paths
- 需要权衡（UX、reliability、maintainability、cost、performance）
- 用户可能一开始不知道最佳选项
核心原则（不可协商）
-
Task-first（尽早捕获）
始终确保一开始就有 task，以便立即记录用户想法。
-
先行动再提问
如果你能从 repo code、docs、configs、conventions 或快速 research 推导答案 — 先做。
-
每条消息一个问题
不要用一串问题压垮用户。问一个、更新 PRD、重复。
-
偏好具体选项
对 preference/decision 问题，提供 2–3 个可行、具体且带 trade-offs 的方案。
-
技术选择 Research-first
如果决策依赖行业 conventions / 相似工具 / established patterns，先 research，再提出选项。
-
Diverge → Converge
初步理解后，主动考虑未来演进、相关场景和 failure/edge cases — 然后收敛到有明确 out-of-scope 的 MVP。
-
不要问 meta questions
不要问“我要搜索吗？”或“你能贴代码让我继续吗？”
如果需要信息：search/inspect。如果被阻塞：问最小阻塞问题。
第 0 步：确保 Task 存在（始终）
任何 Q&A 前，确保 task 存在。如果没有，立即创建一个。
- 使用从用户消息派生的临时工作标题。
- 标题不完美没关系 — 稍后在 PRD 中细化。
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
使用不带日期前缀的 slug。task.py create 会自动添加 MM-DD-
目录前缀。
立即用已知内容创建/初始化 prd.md。本项目中的 PRD 必须使用中文撰写；仅保留 commands、paths、placeholders、专有名词或用户原文中必须逐字保留的内容。
# brainstorm: <short goal>
## 目标
<一段话：做什么 + 为什么>
## 已知信息
* <来自用户消息的事实>
* <从 repo/docs 发现的事实>
## 临时假设
* <需要验证的假设>
## 待确认问题
* <仅保留阻塞性 / 偏好类问题；列表保持简短>
## 需求（迭代中）
* <从已知内容开始>
## 验收标准（迭代中）
* [ ] <可测试标准>
## 完成定义（团队质量门槛）
* 已添加/更新 tests（适用时包括 unit/integration）
* Lint / typecheck / CI 通过
* 行为变化时已更新 docs/notes
* 风险较高时已考虑 rollout/rollback
## 不在范围内（明确）
* <本 task 不会做什么>
## 研究参考
* <links to research/*.md or external references>
对于复杂 tasks，还要创建/更新：
# design.md
## 技术设计
<边界、contracts、data flow、兼容性、tradeoffs>
## Rollout / Rollback
<适用时填写 operational notes>
# implement.md
## 实现 Checklist
- [ ] <有序 implementation step>
## Validation
- <lint/typecheck/test command>
## Review Gates（检查门槛）
- <开始/完成前的人类或技术 checkpoint>
第 1 步：Auto-Context（提问前先做）
在问“代码长什么样？”这类问题前，自行收集 context：
Repo 检查清单
- 识别可能受影响的 modules/files
- 定位现有 patterns（相似 features、conventions、error handling style）
- 检查 configs、scripts、现有 command definitions
- 记录任何约束（runtime、dependency policy、build tooling）
文档检查清单
- 查找 existing PRDs/specs/templates
- 查找 command usage examples、README、ADRs（如有）
将 findings 写入 task artifacts：
- 添加到
已知信息
- 将 technical findings 适当地写入
research/*.md、design.md 或 implement.md
第 2 步：分类复杂度（仍有用，但不作为 task 创建门槛）
| 复杂度 | 标准 | 动作 |
|---|
| Trivial | 单行修复、typo、明显变更 | 跳过 brainstorm，直接实现 |
| Simple | 目标清晰、1–2 个文件、scope 明确 | 问 1 个确认问题，然后实现 |
| Moderate | 多个文件，有一些歧义 | 轻量 brainstorm（2–3 个高价值问题） |
| Complex | 目标模糊、架构选择、多种方案 | 完整 brainstorm |
注意：Task 已在第 0 步存在。分类只影响 brainstorming 深度。
第 3 步：问题门禁（只问高价值问题）
在提出任何问题前，先通过以下门禁：
门禁 A — 我能否不问用户而推导出来？
如果答案可通过以下方式获得：
- repo inspection（code/config）
- docs/specs/conventions
- 快速 market/OSS research
→ 不要问。 获取它、总结它、更新 PRD。
门禁 B — 这是 meta/lazy question 吗？
示例：
- "Should I search?"
- "Can you paste the code so I can proceed?"
- "What does the code look like?" (when repo is available)
→ 不要问。 采取行动。
门禁 C — 这是什么类型的问题？
- Blocking：没有用户输入无法继续
- Preference：存在多个有效选择，取决于 product/UX/risk 偏好
- Derivable：应通过 inspection/research 回答
→ 只询问 Blocking 或 Preference。
第 4 步：Research-first 模式（技术选择时强制）
触发条件（任一满足 → research-first）
- task 涉及选择 approach、library、protocol、framework、template system、plugin mechanism 或 CLI UX convention
- 用户询问 “best practice”、“how others do it”、“recommendation”
- 用户无法合理枚举选项
委托给 trellis-research sub-agent（不要 inline research）
对每个 research topic，通过 Task tool spawn 一个 trellis-research sub-agent — 不要在主对话中 inline 执行 WebFetch / WebSearch / gh api。
原因：
- sub-agent 有自己的 context window → 不会用原始 tool output 污染 brainstorm context
- 它会将 findings 持久化到
{TASK_DIR}/research/<topic>.md（契约 — 见 workflow.md Phase 1.2）
- 它只向 main agent 返回
{file path, one-line summary}
- 独立 topics 可以并行化 — 在一次 tool call 中 spawn 多个 sub-agents
Codex exception：在 Codex CLI 上，不要为 research-first mode dispatch trellis-research — 直接 inline 做 research（main session 中的 WebFetch / WebSearch），并自行将 findings 写入 {TASK_DIR}/research/<topic>.md。原因：Codex spawn_agent 以 fork_turns="none" 运行 sub-agents（隔离 context，无 parent session inheritance），因此 research sub-agent 无法通过 task.py current 解析 active task path，会静默中止且不产出文件。Codex 上 inline research 可避免此失败模式。专门为 Codex 放宽 workflow.md 中 3+ inline research calls limit（B 规则）。
Agent type：trellis-research
Task description template："Research ; persist findings to {TASK_DIR}/research/<topic-slug>.md."
❌ Bad (what you must NOT do):
Main agent: WebFetch(url-A) → WebFetch(url-B) → Bash(gh api ...)
→ WebSearch(q1) → WebSearch(q2) → ... (10+ inline calls)
→ Write(research/topic.md)
→ 用原始 HTML/JSON 污染 main context，消耗 tokens。
✅ Good:
Main agent: Task(subagent_type="trellis-research",
prompt="Research topic A; persist to research/topic-a.md")
+ Task(subagent_type="trellis-research",
prompt="Research topic B; persist to research/topic-b.md")
+ Task(subagent_type="trellis-research",
prompt="Research topic C; persist to research/topic-c.md")
→ Reads research/topic-{a,b,c}.md after they finish.
Research steps（传入每个 sub-agent prompt）
每个 trellis-research sub-agent 应：
- 为其 topic 识别 2–4 个可比较 tools/patterns
- 总结 common conventions 及其存在原因
- 将 conventions 映射到我们的 repo constraints
- 将 findings 写入
{TASK_DIR}/research/<topic>.md
Main agent 随后读取持久化文件，并在 PRD 中产出 2–3 个可行 approaches。
Research output format（PRD）
PRD 本身只应引用已持久化 research files，不要重复其内容。添加指向 research/*.md 的 ## 研究参考 section。
可选：添加 convergence section，列出由 research 派生的可行 approaches：
## 研究参考
* [`research/<topic-a>.md`](research/<topic-a>.md) — <one-line takeaway>
* [`research/<topic-b>.md`](research/<topic-b>.md) — <one-line takeaway>
## 研究备注
### 相似工具的做法
* ...
* ...
### 本 repo/project 的约束
* ...
### 当前可行方案
**方案 A：<name>**（推荐）
* 工作方式：
* 优点：
* 缺点：
**方案 B：<name>**
* 工作方式：
* 优点：
* 缺点：
**方案 C：<name>**（可选）
* ...
然后问一个偏好问题：
- "你更偏好哪个方案：A / B / C（或其他）？"
第 5 步：扩展扫描（DIVERGE）— 初步理解后必需
当你能总结目标后，在收敛前主动拓宽思考。
扩展类别（每类保持 1–2 bullet）
-
未来演进
- 这个 feature 在 1–3 个月后可能变成什么？
- 现在值得保留哪些 extension points？
-
相关场景
- 哪些相邻 commands/flows 应与此保持一致？
- 是否有 parity expectations（create vs update、import vs export 等）？
-
Failure 与 edge cases
- Conflicts、offline/network failure、retries、idempotency、compatibility、rollback
- Input validation、security boundaries、permission checks
扩展消息模板（发给用户）
我理解你想实现：<current goal>。
进入设计前，我先快速扩展思考三个类别（避免后续返工）：
1. 未来演进：<1–2 bullets>
2. 相关场景：<1–2 bullets>
3. Failure/edge cases：<1–2 bullets>
这次 MVP 你希望包含哪些内容（或都不包含）？
1. 只做当前需求（minimal viable）
2. 增加 <X>（为未来扩展预留）
3. 增加 <Y>（提升健壮性/一致性）
4. 其他：描述你的偏好
然后更新 PRD：
- MVP 包含什么 →
需求
- 排除什么 →
不在范围内
第 6 步：Q&A 循环（CONVERGE）
规则
-
每条消息一个问题
-
可行时优先 multiple-choice
-
每次用户回答后：
- 立即更新 PRD
- 将已回答项从
待确认问题 移到 需求
- 用可测试 checkboxes 更新
验收标准
- 澄清
不在范围内
问题优先级（推荐）
- MVP scope boundary（包含/排除什么）
- Preference decisions（展示具体选项后）
- Failure/edge behavior（仅限 MVP-critical paths）
- Success metrics & Acceptance Criteria（什么证明它可用）
推荐问题格式（multiple choice）
对于 <topic>，你更偏好哪种方案？
1. **选项 A** — <含义 + trade-off>
2. **选项 B** — <含义 + trade-off>
3. **选项 C** — <含义 + trade-off>
4. **其他** — 描述你的偏好
第 7 步：提出 Approaches + 记录 Decisions（复杂 tasks）
当 requirements 足够清晰后，提出 2–3 个 approaches（如果还没通过 research-first 完成）：
基于当前信息，这里有 2–3 个可行方案：
**方案 A：<name>**（推荐）
* 做法：
* 优点：
* 缺点：
**方案 B：<name>**
* 做法：
* 优点：
* 缺点：
你更偏好哪个方向？
将结果作为 ADR-lite section 记录到 PRD：
## 决策（ADR-lite）
**背景**：为什么需要这个决策
**决策**：选择了哪个方案
**后果**：Trade-offs、风险、潜在未来改进
第 8 步：最终确认 + 实现计划
当待确认问题已解决，用结构化中文摘要确认完整需求：
最终确认格式
这是我对完整需求的理解：
**目标**：<一句话>
**需求**：
* ...
* ...
**验收标准**：
* [ ] ...
* [ ] ...
**完成定义**：
* ...
**不在范围内**：
* ...
**Artifact status**：
* prd.md：<ready / needs update>
* design.md：<not needed for lightweight / ready / missing>
* implement.md：<not needed for lightweight / ready / missing>
这样是否正确？如果是，下一步是在 `task.py start` 前进行 planning review。
Subtask 拆分（复杂 Tasks）
对包含多个独立 work items 的复杂 tasks，创建 subtasks：
CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
PRD 目标结构（最终）
prd.md 应收敛为：
# <Task Title>
## 目标
<为什么 + 做什么>
## 需求
* ...
## 验收标准
* [ ] ...
## 完成定义
* ...
## 研究参考
* <links to research/*.md or external references>
Anti-Patterns（严格避免）
- 向用户询问可从 repo 推导出的 code/context
- 在展示具体选项前要求用户选择 approach
- 关于是否 research 的 meta questions
- 狭窄停留在初始请求，不考虑 evolution/edges
- 让 brainstorming 漂移而不更新 PRD
与 Start Workflow 的集成
brainstorm 完成后（第 8 步确认通过），flow 继续进入 Task Workflow 的 planning review gate：
Brainstorm
步骤 0：创建 task directory + 初始化中文 PRD
步骤 1–7：发现 requirements，research，converge
步骤 8：最终确认 → 用户批准 planning artifacts
↓
Task Workflow Phase 1（Plan）
轻量 task → PRD-only 可以足够
复杂 task → 需要 design.md + implement.md
Sub-agent 平台 → 整理 implement.jsonl / check.jsonl manifests
→ Review gate → task.py start
↓
Task Workflow Phase 2（Execute）
Implement → Check → Complete
task directory 和 PRD 已在 brainstorm 中存在，但 Phase 1 不会被跳过；它负责 artifact review 和 task.py start gate。
相关 Commands
| Command | 使用时机 |
|---|
``start (Trellis command) | 触发 brainstorm 的入口点 |
``finish-work (Trellis command) | implementation 完成后 |
``update-spec (Trellis command) | 工作期间出现新 patterns 时 |
