---
name: sdd-flow-kit
description: 最高优先级触发。凡用户表达“开发/进行/实现 <产品> <版本> 需求/版本”，例如 ADI_V2.3.4、OMS V1.24.5、BreakX 1.0.2、欢盟 V2.1.0，必须第一步执行 `npx sdd-flow-kit guard "<用户原话>" -y --agent {{AGENT_NAME}}` 或 invoke/run。禁止先执行 openspec new change、OPSX Propose 或修改 src/e2e；成功后必须读取 NEXT.md 与 .session-state.json。
---

# SDD Flow Kit（{{PROJECT_KIND}} — 脚本门禁）

## 触发即执行（第一步，禁止跳过）

用户一旦表达版本开发意图，**在本回合终端执行**（项目根 = 安装 sdd-flow-kit 的目录，如 `frontend/`）：

```bash
npx sdd-flow-kit guard "<用户原话>" -y --agent {{AGENT_NAME}}
```

若 `guard` 不可用，再退化为：

```bash
npx sdd-flow-kit run --product {{DEFAULT_PRODUCT}} --version <版本号> -y --agent {{AGENT_NAME}}
```

然后 **只读** `openspec/PRD/<runId>/NEXT.md` 与 `.session-state.json`，按其中**本步**命令执行；**exit code ≠ 0 必须停止**。

### 每步协议（防误判提前结束）

```bash
npx sdd-flow-kit status --project-root <安装根> --run-id <runId>   # 或 resume
# 只读：.session-state.json + NEXT.md（单步指令）
# 禁止：每步通读 01–08 / 07 / FLOW-MAP 全流程说明书
# 只做 NEXT 中「本步」；成功后再 status/resume
# mayStop=false 时禁止「后续待办 / 可选手动 deliver」式收工
```

断点续传（同一 run，禁止 guard 重开）：

```bash
npx sdd-flow-kit resume --project-root <安装根> --run-id <runId>
npx sdd-flow-kit resume --project-root <安装根> --run-id <runId> --exec   # 仅 kind=cli
```

全流程地图仅排障：`FLOW-MAP.md`（**非**每步必读）。

## 文档职责（SSOT）

| 文档 | 职责 |
|------|------|
| `01` | 业务概述、风险（**非**完整验收） |
| `05` | **唯一验收 SSOT** — 从 `source/PRD.md` 逐条抽 AC |
| `04` | 技术方案，须引用 `[AC-XX]` |
| `tasks.md` | 每条任务标题含 `[AC-XX]` |

## 铁律（防 vibe coding）

1. `docModeOnly: true` 时 **禁止** 修改 `src/`、`frontend/src/`、`e2e/`。
2. 用户粘贴确认点后：先生成 **`05 → 04 → 01/02`**，再 **必须**：
   ```bash
   npx sdd-flow-kit gate --project-root <安装根> --run-id <runId> --expect docs-closed
   npx sdd-flow-kit phase advance --project-root <安装根> --run-id <runId> --to docs-done
   ```
3. propose 后 **必须** `gate ac-ready`（P0 映射到 spec/tasks）才能 `phase impl`。
4. **仅当** `gate --expect impl-allowed` 通过后，才允许按 `tasks.md` 改业务代码。
5. **Apply 前必读**：`source/PRD.md` 对应章节 + `05-验收清单.md`（tasks 是子集，不能替代 PRD）。
6. **deliver 前必须** `prd-diff` + `gate prd-coverage`（脚本 PRD 语义 diff + 08 复查）+ `gate ac-signed`。
7. 提案/实现 **必须** 读并执行：
   - `.cursor/skills/opsx-superpowers-workflow/SKILL.md`
   - `openspec-propose` → `openspec-apply-change` → `pnpm run opsx:delivery-pipeline -- <change>`
8. TDD/Playwright 遵循 `LAYERED-TESTING.md`（L2 交互契约、L3 每页 E2E）。
9. **`executionMode=full-chain`（默认）**：矛盾点闭合后 **禁止** 以待办清单结束回合；必须 C→D→E 直至 `deliver` exit 0。

## 执行模式（`.session-state.json`）

| 口令 | `executionMode` | `strictCommands` | 行为 |
|------|-----------------|------------------|------|
| （默认） | `full-chain` | `false` | 确认后同一回合跑到底 |
| `执行模式：确认后全链路` | `full-chain` | — | 同上，禁止中途停止 |
| `执行模式：分阶段确认` | `staged-confirm` | — | 每阶段完成后等人确认 |
| `执行模式：严格命令` | — | `true` | 禁止等价命令替代 gate 链路 |
| `严格SOP，不可替代`（兼容） | `staged-confirm` | `true` | 分阶段确认 + 严格命令 |

```bash
npx sdd-flow-kit session mode --run-id <runId> --execution-mode full-chain
npx sdd-flow-kit chain --run-id <runId> --change <name> --from docs-done
```

## 回合结束条件

- ✅ 唯一合法出口：`gate shipped` + `deliver` exit 0
- ⛔ 禁止「骨架已完成」「后续待办」式收尾（`full-chain` 时）
- ⛔ 禁止在 `tasks.md` 未全 `[x]` 时宣称完成

## 严格命令模式（`strictCommands=true`）

与是否分阶段暂停**正交**；可与 `full-chain` 组合：

1. 必须严格按 `NEXT.md` 中的 gate/phase 链路执行，禁止“等价方式”替代。
2. Step1 须走 Confluence/脚本链路；除非用户明确允许，禁止手动回填代替。
3. 阶段 B 的 `04` 须可执行且逐条引用 AC-ID。
4. 阶段 C 须 `/opsx-propose`（输入 **05 + 04 + 02 + UI**），禁止仅用 `sdd-flow-kit propose` 代替 AI 提案生成。

## 分阶段确认模式（`executionMode=staged-confirm`）

1. 每阶段前先输出：`本次计划命令清单（逐条）`
2. 每阶段后输出：`门禁结果 + 证据文件路径 + 下一步命令`
3. **等待用户确认**后再进入下一阶段

## 阶段摘要

| 阶段 | 动作 |
|------|------|
| A | Step1 PRD → `gate prd-fetched` → `phase after-prd` |
| A2 | 提问模式仅 03 → `gate questions-open` |
| B | 用户确认后 **05→04→01/02** → `gate docs-closed` → `phase docs-done` |
| C | `propose` + artifacts → **`propose-remediate`** → **`demo-layout-capture/analyze`**（闭合 16 布局合约）→ `phase propose-done` |
| D | `phase impl`（须 `layout-contract-ready`）→ `gate impl-allowed` → `/opsx-apply`（结构跟合约，控件跟仓库 UI）→ pipeline |
| E | `prd-review` → `prd-diff` → `gate prd-coverage` → **`demo-fidelity-review --auto`** → `gate demo-fidelity-ready` → `validate` → **05 签收** → `deliver` |

## 环境

- agent: {{AGENT_NAME}}
- 全量安装: `npx sdd-flow-kit install --project {{PROJECT_KIND}} -y`
- 分层测试: `.cursor/skills/sdd-flow-kit/LAYERED-TESTING.md`
- 本地 OPSX: `SDD_OPSX_WORKFLOW_PACKAGE=file:../../opsx-workflow`

## 超大任务（isLargeTask=true）

当 `analyze-task` 检测到大任务时：

1. 读取 `06-Subagent执行计划.md` 了解拆分策略
2. 评估自身上下文是否足以串行完成所有子任务
3. 若上下文不足，使用 subagent 并行执行：
   ```bash
   # 查看状态
   npx sdd-flow-kit execute-subagent --run-id <runId> --status
   # 执行全部（按依赖拓扑排序）
   npx sdd-flow-kit execute-subagent --run-id <runId> --all --agent {{AGENT_NAME}}
   # 或逐步执行
   npx sdd-flow-kit execute-subagent --run-id <runId> --next --agent {{AGENT_NAME}}
   ```
4. 若上下文充足：自行按 `tasks.md` 顺序执行
5. 子任务全部完成后读取 `.subagents/BATCH-RESULT.md` 汇总
6. 运行 `delivery-pipeline` 做最终验证（子任务不单独跑 pipeline）

详见：`.cursor/skills/sdd-flow-kit/SUBAGENT-EXECUTION.md`