Files
dth/docs/superpowers/dispatch-helpers/brainstorming-openspec-mapping.md
T
xstudio agentandClaude Opus 4.8 9eeb9a8030 feat(dispatch-helpers): A-2 prep-sandbox-space.sh + dispatch-preflight.sh; B-2 brainstorming↔openspec 映射; E-2 prompt 模板
A-2 prep-sandbox-space.sh:
- 修 A-1 mount 断链:拷贝 workspace 当前状态到 /tmp/xstudio-sandbox/<hash>/space/
- +force 选项覆盖已有空间
- 推断 workspaceRoot 走 last_workspace 文件兜底

A-2 dispatch-preflight.sh:
- 4 项自检:docker / 容器 up / space 可写 / .claude/skills 拷到位
- + bonus: workspaceRoot ai-config
- 自动调 prep-sandbox-space / prep-sandbox-skills / auto-setup-xstudio-ai
- 实测:ccc workspace 全部 ✅

B-2 brainstorming-openspec-mapping.md:
- design.md → chg 工件字段映射表
- naming 约定 (capability / chg_id / S 编号 / C 编号)
- chg 创建 10 步 checklist
- 与 superskills using-superpowers 冲突解决

E-2 prompt-template.md:
- 6 段 prompt 结构 (Header / Cache / Don't / 工件 / 步骤 / 汇报)
- 完整 chg_0005 实例
- 模板生成脚本占位(待下次写)

Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-09-28 13:57:57 +08:00

6.7 KiB
Raw Blame History

Brainstorming ↔ Openspec 映射指南(B-2)

编制:2026-09-28 · 配合 learnings §B-2 状态:host-side 文档;给"同时激活 brainstorming + openspec"的场景用


1. 背景

两个 skill 看起来重叠:

  • brainstorming(superskills):设计阶段产出 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
  • ai-collab-framework(openspec):每个 chg 产出 proposal/spec/tasks/testcases/map.yaml 五件套

实际分工:

skill 阶段 产出
brainstorming 变更前(跨多个 chg 的整体设计) design.md(一份)
ai-collab-framework 每个 chg(具体行为的 openspec 工件) 五件套(一份/每个 chg)

2. 调用顺序(必须)

Phase 1: brainstorming 跑 → design.md 写好 → 用户 review
   ↓ 批准
Phase 2: design.md 拆解成 N 个 chg,每个写 openspec 五件套
   ↓
Phase 3: 每个 chg 走 xstudio-sandbox-dispatch 派单

关键:brainstorming 的 design doc 不替代 chg 工件;design doc 是"前置设计 spec",chg 工件是"具体执行的 contract"。

3. design.md → chg 工件的映射表

design.md 段落 chg 工件字段 说明
# Spec: <capability> 标题行 spec.md # Spec: 标题 + map.yaml # spec: <capability>@<chg_id> capability 名必须一致,chg_id 必须对应目录 basename
## Requirement EARS 句式 spec.md ## Requirement 段 复制保留 + 改写为 capability 级 EARS
## ADDED Scenarios (### S<n>) spec.md ## ADDED Scenarios capability 级全局 S 编号,跨 chg 连续
## MODIFIED Scenarios spec.md ## MODIFIED Scenarios 整块从 openspec/specs//spec.md 拷贝再改(modality,modifies 是完整替换)
## REMOVED Scenarios spec.md ## REMOVED Scenarios 含 **Reason** + **Migration** 两行
## Why + ## Who + ## Scope + ## Non-Goals + ## Acceptance proposal.md 同名段 改写为 chg 级(带 change_id frontmatter)
## Impact proposal.md ## Impact 影响 capability 名(应一致)
隐含的"任务列表"(脑图) tasks.md # Tasks (DAG) 把脑图转 YAML 节点(id / type / depends_on / output / verification)
## UX / Interaction spec.md 同名段 UI 类变更才需要,非 UI 不写
隐含的"每个 scenario 对应一个 case" testcases.md ### C<n>_<slug> one-to-many 也行(map.yaml 显式声明)

4. 命名约定(避免冲突)

4.1 capability 级 S 编号

  • capability 在 openspec/specs/<cap>/spec.md 主 spec 已有 → 新 chg 接续最大号
  • capability 是新的 → 从 S1 起
  • 新 chg 用 delta 段(## ADDED/MODIFIED/REMOVED Scenarios),非 delta 写法(## Concrete Scenarios)会有迁移提示

4.2 chg_id

格式:chg_NNNN_<capability-scope>_<change-slug>

  • NNNN:四位数字,按 archive 一起扫(不重用)
  • capability-scope:与 capability 名一致
  • change-slug:动词/名词短语(kebab-case)

例:chg_0003_dispatch_helpers、chg_0004_experiment_platform_frontend

4.3 capability 名

  • 单一 capability:<scope>(如 experiment_platform)
  • 跨 capability 复合 chg:拆成多个 chg,不要硬塞进一个

5. testcases 命名约定

格式:C<数字>_<slug>(C1_list_default)

  • 每个 scenario 至少 1 条 case(map.yaml 显式声明)
  • one-to-many OK:S4 → [C4_no_token_600, C7_perm_smoke_passes]
  • 数字连续,从 1 起
  • 跨 chg 不重用(避免追溯混淆)

6. 模板速查(chg 工件最小集)

proposal.md 最小 frontmatter

---
change_id: chg_NNNN
status: proposed
owner: pm@team
stakeholders: [pd, tm, qa, dev]
priority: P1
target_release: v0.X
created: YYYY-MM-DD
skip_coverage: false   # 纯 refactor 设 true
---

spec.md 最小结构

# Spec: <capability 名称>

## Requirement
WHEN <trigger> THE SYSTEM SHALL <response>。

## ADDED Scenarios

### S<n> <场景名>
- **WHEN** <触发动作>
- **AND** <前置条件>
- **THEN** <可观测结果>

## UX / Interaction(UI 类才填)
- 原型位置:...
- 交互决策:...

tasks.md 最小结构

# Tasks (DAG)
- id: T1
  type: architect | implementer | tester | qa
  depends_on: []
  output: <path>
  verification: <check>

testcases.md 最小结构

### C<n>_<slug>
- Scenario: S<n>
- Type: unit | integration | e2e | ux
- Priority: P0 | P1 | P2
- Given: ...
- When: ...
- Then: ...
- Automated: true | false
- Bound Task: T<n>   # 必须在 tasks.md 真实存在

testcases.map.yaml 最小结构

# spec: <capability>@<chg_NNNN>
scenarios:
  - id: S1
    cases: [C1_<slug>, C2_<slug>]
gate:
  blocking_gap_tolerance: 0
  implementation_files:
    - src/<module>/
  test_files:
    - tests/<module>/

7. 流程清单(chg 创建)

□ 1. 读 design.md,按"## ADDED Scenarios"分 chg(每 chg 一个 delta 段)
□ 2. mkdir -p openspec/changes/chg_<NNNN>_<slug>
□ 3. cp templates/{proposal,spec,tasks,testcases,testcases.map.yaml}.md chg_<NNNN>_<slug>/
□ 4. 改 frontmatter:
     - change_id: chg_<NNNN>
     - skip_coverage: true(纯基础设施/无行为变更)
□ 5. 写 spec.md:# Spec: <capability> + delta 段
□ 6. 写 tasks.md:T1=architect, T2=implementer, T3=tester (T 编号 capability 内唯一)
□ 7. 写 testcases.md:Bound Task 必须真实存在
□ 8. 写 testcases.map.yaml:scenario ↔ case 绑定
□ 9. 写 proposal.md:why/scope/acceptance
□ 10. 跑门禁:PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh
     - PASS → 可 dispatch
     - FAIL → 修工件

8. 与 superskills using-superpowers 的冲突解决

brainstorming skill 要求"设计 doc 写好后等用户批准才能 writing-plans"。 openspec 的 chg 工件是 ai-collab-framework 自带的 deliverable,不经过 superskills writing-plans。

冲突解决(已写在 learnings §B-3):

  • 同时激活 brainstorming + openspec → 以 openspec 工件 为权威 approval artifact
  • brainstorming 的 design doc 作为前置 spec 即可(用户批准 design.md 即视为批准 openspec chg)
  • 不需要 writing-plans skill

9. 验证 checklist

  • design.md 写好 → commit 3f5f32f
  • chg_0003/0004/0005 用本流程走通
  • check_spec_coverage.sh gap=0
  • dispatch skill 文档同步更新(待 user 决策)

10. 相关文件

  • docs/superpowers/learnings/2026-09-28-dispatch-session.md §B-2 / §B-3
  • docs/superpowers/specs/2026-09-28-xstudio-dispatch-improvements.md(design doc 范例)
  • openspec/scripts/check_spec_coverage.sh — 门禁脚本
  • ~/.claude/skills/ai-collab-framework/SKILL.md §5/§6/§7/§8 — 6 条门禁硬约定