t-dream

Files (1)

• SKILL.md

SKILL.md (first lines)

# 上下文整理与工程事实重组

运行时边界：`${CLAUDE_PLUGIN_ROOT}/protocols/runtime-boundaries.md`（写报告或调用目标项目脚本前读）
需求来源边界：`${CLAUDE_PLUGIN_ROOT}/protocols/requirement-source-contract.md`（区分草稿与已发布需求来源时读）
候选问题结构、评分权重、报告结构和模式写入边界：`${CLAUDE_PLUGIN_ROOT}/protocols/dream-report-contract.md`（构造 subagent 输出、计算评分或写报告前读）

## 目标
- 识别 PRD、用户故事、设计、任务、Demo 注释、实现事实和项目结构中偏离当前可信上下文的问题，并给出收敛建议。
- 识别并减少错误信息累积：重复 PRD、历史过程文档、过期术语、失效设计、冲突业务规则、错误能力承诺和误导性实现说明。
- 评估 PRD 目录、代码目录、模块边界、测试布局、Demo 布局、`.ai/` 运行时产物组织是否合理，是否支持后续 AI agent 快速定位、窄范围修改和可靠验证。
- 建立 PRD -> 用户故事 -> 设计/任务 -> 代码 -> 测试/Demo 的 traceability 视图，指出断链、错链、重复链和缺失证据。
- 对比 PRD 与实现事实，检查能力边界、模型约束、校验、权限、业务逻辑、前端可见行为和 Demo 覆盖事实的差异。
- 通过专用 subagent 和多个 `general_agent` 按维度并行检查，主流程只负责编排、验证、合并、裁决和必要写入。
- 输出可追溯证据、差异分级和应修正文档还是实现的建议。

`t-dream` 聚焦目标项目当前上下文是否干净、可信、结构合理，并能继续支撑后续 AI 编程流程。

## 参数
| 参数 | 说明 |
|---|---|
| `[feature]` | 可选。聚焦指定功能、模块或领域关键词 |
| `--all` | 检查全部可识别 PRD / 模块 |
| `--deep` | 启用后端模块级深度一致性检查 |
| `--phase <phase>` | 只执行该交付阶段的一致性检查；backend 隐含深度检查 |

`t-dream` 所有模式都只读，不修改目标项目文档或代码；PRD 治理内容（合并、归档、重写、改引用）只作为报告建议输出，见"PRD 治理建议"。未传入 `[feature]` 或 `--all` 时，先提示可用模块来源是 `docs/prd/**/*.md`，再建议用户指定范围。

## 输入范围
- PRD：`docs/prd/**/*.md`（排除模板、索引和说明文件）
- 用户故事：`docs/user-stories/**/*.md`、`.ai/user-stories/**/*.md`
- PRD 草稿：`.ai/prd/**/*.md`
- 设计与任务：`.ai/design/**/*.md`、`.ai/task/**`
- Demo 测试：Web 为 `demo/e2e/**/*.e2e.ts`，Flutter 为 `patrol_test/**/*_test.dart`
- 实现代码：按目标项目真实结构定位 backend、frontend、extension、miniapp、flutter、shopify（应用本体与 `extensions/`）、demo 相关实现
- 项目结构：`docs/`、`.ai/`、各交付端与 test 目录、README、AGENTS/CLAUDE 类上下文入口、ADR 或架构说明（如存在）

## 执行模型

`t-dream` 是主控编排 skill，不应由主线程独自完成所有检查。主线程负责确定范围、构造共享上下文、并行启动 subagent、验证候选问题、合并结果、写入最终报告。

整体采用类似 code review 的两阶段机制：
- 并行发现：专用 subagent 与多个 `general_agent` 从不同维度独立发现候选问题。
- 统一验证：主线程或专门的验证 subagent 根据真实文件证据过滤误报、去重、定级和评分。

模式语义（`audit` / `phase` / `deep` 的写入边界和覆盖范围）以 `${CLAUDE_PLUGIN_ROOT}/protocols/dream-report-contract.md` 的模式表为准。补充约定：
- 默认聚焦 context health：当前上下文是否准确、收敛、可导航、可追踪、结构上可持续。措辞、格式、风格偏好仅在导致业务含义失真、查找成本显著增加或后续 agent 容易误用时进入问题清单。
- PRD 治理建议只写入报告，不在本 skill 内执行任何治理写入。
- `--phase`（阶段一致性模式）适合对应交付阶段收口，只输出该阶段一致性结论，不输出上下文治理或结构组织结论；阶段必须是目标项目真实存在的交付端，不得为满足命令而编造检查范围。

`--all` 预算策略：
- 默认先做索引级健康扫描：PRD 文件、标题、索引引用、用户故事引用、draft story 引用、设计/任务入口、明显重复/过期关键词和结构入口。
- 只对高风险模块深挖。高风险信号包括：索引缺失、同名/近义 PRD 重复、用户故事或 Demo 指向旧 PRD、PRD 声明和代码关键词明显错位、权限/租户/状态规则冲突信号。
- 若用户要求全量深挖，必须显式使用 `--all --deep`。

## PRD 治理建议

用户请求整理、合并、精简 PRD 或清理过期过程文档时，仍在只读 audit 内完成：`context-curator` 识别重复、过期、冲突内容并输出整理计划，主线程验证后把 PRD 治理建议（合并、归档、重写、改引用计划）写入报告对应章节。

- 治理判定原则、合并判定和计划要素读取 `${CLAUDE_PLUGIN_ROOT}/guides/product/prd-governance.md`。
- 建议结构遵循 `${CLAUDE_PLUGIN_ROOT}/protocols/dream-report-contract.md` 的 PRD Governance Recommendations。
- 本 skill 不执行任何治理写入；归档、删除、合并、改引用由用户确认后另行执行。

## 并行 subagent 维度

默认按以下维度并行调用 subagent：

| 维度 | subagent 任务 |
|---|---|
| PRD 上下文治理 | 使用 `context-curator` 识别重复、过期、冲突、过程化和非权威 PRD 内容 |
| 结构组织评估 | 使用 `structure-review` 评估 PRD、代码、测试、Demo、`.ai/` 目录和模块边界是否合理 |
| PRD 描述准确性 | 使用 `general_agent` 提取关键 PRD 声明，并核对是否被实现事实支撑；默认 audit 只做高风险声明抽样 |
| 用户故事与验收描述 | 核对用户故事、GWT、验收标准是否与 PRD 和实现一致 |
| Demo 描述与覆盖事实 | 核对 Demo 测试注释、故事映射、断言和实际覆盖是否准确（web-demo / extension-demo / flutter-demo 阶段的一致性维度） |
| 后端实现一致性 | 检查 API 能力边界、模型、校验、权限、业务逻辑 |
| 前端实现一致性 | 核对页面、组件、交互、权限可见性与 PRD/故事描述是否一致 |
| 扩展实现一致性 | 核对入口、消息、存储、权限与 PRD/故事描述是否一致 |
| 小程序实现一致性 | 核对页面、平台能力与 PRD/故事描述是否一致 |
| Flutter 实现一致性 | 核对 View、状态、数据层与 PRD/故事描述是否一致 |
| Traceability | 核对 PRD -> 用户故事 -> 设计/任务 -> 代码 -> 测试/Demo 链路是否存在断链、错链或重复链 |
| 候选问题验证 | 复核各维度候选问题是否有文件定位、真实证据、合理分级和修复方向 |

`--phase` 只启动该阶段对应的一致性维度和"候选问题验证"，阶段与维度的映射、一致性对象和证据定位以 `${CLAUDE_PLUGIN_ROOT}/protocols/dream-report-contract.md` 的 Phase Consistency 为准。`--phase backend` 按模块调用 `backend-consistency` 做专项深度检查；`--deep` 在非 phase 模式下于"后端实现一致性"之外，额外按模块调用 `backend-consistency`。`backend-consistency` 在 `t-dream` 调用下必须只返回结构化结果，不自行写入独立一致性报告。

### subagent 调用要求
- 使用 `Task` 或 `Agent` 启动 `subagent_type="context-curator"`、`subagent_type="structure-review"`、`subagent_type="general_agent"`；调用按 `${CLAUDE_PLUGIN_ROOT}/protocols/subagent-dispatch.md` 执行，`general_agent` 为内置 agent，按协议跳过注入。
- 各 subagent 必须只读检查，不修改代码或文档；只输出候选问题，不直接决定最终报告结论。
- 各 subagent 必须接收同一份共享上下文包，保持检查范围一致；并行执行时各维度结论互不污染，冲突由主线程在汇总阶段处理。
- 候选问题字段、置信度阈值和"专项 agent 可增加的字段"以 `${CLAUDE_PLUGIN_ROOT}/protocols/dream-report-contract.md` 为准；最终 P0/P1 必须经过验证且置信度不低于 80。

共享上下文包必须包含：
- 检查范围：`[feature]` / `--all` / `--phase` / `--deep`。
- PRD 文件列表和目标模块列表。
- 相关用户故事、Demo 测试和实现检索路径。
- 设计、任务、README、AGENTS/CLAUDE、ADR 或架构说明路径（如存在）。
- 上下文健康判定规则、结构组织判定规则、描述准确性判定规则、P0/P1/P2/P3 分级规则和 `${CLAUDE_PLUGIN_ROOT}/protocols/dream-report-contract.md` 报告格式要求。
- 当前目标是整理和重组当前工程上下文。

## 执行流程

### 1. 确定检查范围
- 解析 `[feature]`、`--all`、`--deep`、`--phase`。
- 传入 `--phase` 时读取 `${CLAUDE_PLUGIN_ROOT}/protocols/task-phase-execution.md` 的 Phases 校验支持值，并确认目标项目存在该交付端；非法或不适用时停止，按该协议提示支持值与可识别交付端。
- 创建 `.ai/quality/`（如不存在）。
- `--all`：扫描 `docs/prd/**/*.md` 自动提取模块名；默认先做索引级健康扫描，只对高风险模块继续深挖。
- `[feature]`：优先匹配 PRD 文件名；若不存在精确文件，按标题、路径、模块名、用户故事引用和测试注释进行模糊定位。
- 校验 PRD 存在；不存在时记录 P1，并列出可用 PRD 来源。

### 2. 构造共享上下文包
主线程先做轻量扫描，不做最终判断：

- 收集 PRD、用户故事、Demo 测试和候选实现文件路径。
- 收集设计、任务、README、AGENTS/CLAUDE、ADR 或架构说明路径。
- 提取模块名、角色名、故事引用、测试引用和关键词。
- 提取目录结构摘要：PRD 分组、backend/frontend/demo/test 主要模块、`.ai/design` 与 `.ai/task` 对应关系。
- 写明本次检查模式、排除项和无法定位的输入。
- 将上下文包传给所有参与的 subagent。

### 3. 并行评估上下文与结构健康
默认先启动两个专项只读 agent：

From timzaak/web-dev-skills, Apache-2.0.

More from timzaak/web-dev-skills