Files
dth/docs/superpowers/dispatch-helpers/brainstorming-openspec-mapping.md
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

188 lines
6.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/<cap>/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
```yaml
---
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 最小结构
```markdown
# Spec: <capability 名称>
## Requirement
WHEN <trigger> THE SYSTEM SHALL <response>。
## ADDED Scenarios
### S<n> <场景名>
- **WHEN** <触发动作>
- **AND** <前置条件>
- **THEN** <可观测结果>
## UX / Interaction(UI 类才填)
- 原型位置:...
- 交互决策:...
```
### tasks.md 最小结构
```markdown
# Tasks (DAG)
- id: T1
type: architect | implementer | tester | qa
depends_on: []
output: <path>
verification: <check>
```
### testcases.md 最小结构
```markdown
### 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 最小结构
```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
- [x] design.md 写好 → commit `3f5f32f`
- [x] chg_0003/0004/0005 用本流程走通
- [x] 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 条门禁硬约定