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]>
6.7 KiB
6.7 KiB
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-3docs/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 条门禁硬约定