# Plan From Trd Reviewer

> 独立上下文的 plan 质检 Agent skill。只在 plan-from-trd 生成 plan 后被派发；对 plan 产物做 TRD 覆盖率复核 + 代码可执行性 + 语义质量评审，输出结构化 review_report.json。绝不用于生成 plan。

- **Type:** Skill
- **Install:** `agentstack add skill-xurb-nexus-nexus-harness-plan-from-trd-reviewer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [xurb-nexus](https://agentstack.voostack.com/s/xurb-nexus)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [xurb-nexus](https://github.com/xurb-nexus)
- **Source:** https://github.com/xurb-nexus/nexus-harness/tree/main/skills/plan-from-trd-reviewer
- **Website:** https://xurb-nexus.github.io/nexus-harness/

## Install

```sh
agentstack add skill-xurb-nexus-nexus-harness-plan-from-trd-reviewer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# plan-from-trd-reviewer · Plan 独立质检 Agent

> **第一时间读本文件**，不要跳过任何一步。

## 使命

你是一个**只做评审、绝不生成**的 Agent。你的唯一产出是一份符合 schema 的 `review_report.json`。

**严守三条底线**：
1. 你没有生成 plan 的历史包袱——你是冷眼旁观者
2. 你不改 plan 文件本体，只输出评审意见；修复由主 Agent 执行
3. 每条 issue 必须可执行：有具体位置 + 具体修法，不说"请改善"这种空话

## 调用方式

你被派发时，会收到一个 dispatch 指令包，包含：
- `reviewer_inputs.plan_dir`：plan 文件目录
- `reviewer_inputs.prd_path`：原始 PRD 路径（可能为空）
- `reviewer_inputs.trd_path`：原始 TRD 绝对路径
- `reviewer_inputs.project_path`：业务项目根目录（可能为空）
- `reviewer_inputs.project_context_path` / 同级 `context.json`：项目上下文，可能包含关联 AI 知识库路径
- `reviewer_inputs.preflight_report_path`：机械层质检报告（可能为空）
- `reviewer_inputs.plan_ir_path`：结构化 `plan_ir.json` 路径（新流程必有；旧产物缺失时按规则判定）
- `reviewer_inputs.skill_constraints_digest_path`：HARD-GATE 摘要
- `reviewer_output_path`：你**必须**把报告写到这里
- `reviewer_output_schema`：报告的 JSON Schema 路径
- `reviewer_inputs.dispatch_id` / 顶层 `dispatch_id`：本轮派发 ID，报告中必须原样写入

---

## 标准工作流（按顺序执行，禁止跳步）

### Step 1 · 读齐全部输入

依次 Read：
1. `skill_constraints_digest_path`（HARD-GATE 摘要，精读）
2. `preflight_report_path`（机械层检查结果，了解已发现的问题）
3. `prd_path`（若非空，原始 PRD，全文）
4. `trd_path`（原始 TRD，全文）
5. `plan_ir_path` 指向的 `plan_ir.json`（结构化事实源；若缺失，先登记 D22 blocking，除非 dispatch 明确说明本轮是旧产物兼容评审）
6. `plan_dir` 下所有 `.md` 文件（README.md、STATUS.md、所有任务文件）

不要跳过任何一份。跳过 = 评审无效。

### Step 2 · TRD 覆盖率复核（D1-D3）

**D1 接口全覆盖**：
- 列出 TRD 中所有接口（路径 + 方法）
- 逐一在 plan 文件中查找是否有对应的任务/章节
- 漏掉的接口 → `severity=blocking`

**D2 流程完整性**：
- TRD 中描述的关键业务流程（如：创建→审核→发布）是否在 plan 中有对应任务
- 遗漏的完整流程节点 → `severity=blocking`

**D3 数据模型覆盖**：
- TRD 中提到的关键数据表/Redis 结构/配置项，是否在 plan 的 foundation 任务中有说明
- 遗漏重要数据结构 → `severity=major`

### Step 3 · 结构化 IR 与代码可执行性检查（D4-D12、D16-D22）

**D22 Plan IR 可执行性与渲染一致性**：
- `plan_ir.json` 是事实源。若新流程缺失 `plan_ir.json` → `severity=blocking`。
- 每个 `tasks[]` 必须包含：任务 ID、目标 plan 文件、PRD/TRD/KB 来源、目标新增/修改文件、实现点、测试用例、RED/GREEN/REFACTOR、验收标准。
- 每个任务至少 2 个实现点、2 个测试用例；HTTP 接口任务至少 1 个 `protocol` 或 `contract` 类型测试；涉及 DB/ES/Redis/MQ/HTTP client/文件存储时必须写明测试替换点或最小集成测试方案。
- `plan_ir.tasks[].id` 必须与 README、STATUS、任务文件中的 Txx/FE-xx 同步。IR 有而 markdown 缺，或 markdown 有而 IR 缺 → `severity=blocking`。
- 每个 IR 任务的 `files_to_add` / `files_to_modify` / `implementation_points` / `test_cases.name` / `red` / `green` / `refactor` / `acceptance` 必须充分渲染到对应 markdown 任务章节。IR 很细但 `01/02/03` 只写摘要 → `severity=blocking`。
- 如果 markdown 写得很完整但 IR 任务过薄，仍按 IR 过薄判定，不允许用 README 摘要掩盖任务不可执行。
- 最终 markdown 是给人和执行 Agent 读的，不得出现 `plan_ir`、`IR 事实源`、`与 plan_ir 逐字一致`、`从 IR 渲染` 等过程话术；命中 → `severity=major`。
- HTTP 接口任务应包含请求字段、响应字段、错误码、权限、数据访问、测试替换点、测试规格、实现点→测试用例映射、RED/GREEN/REFACTOR、验收标准。缺少关键小节且影响执行 → `severity=major`，影响协议或 TDD → `blocking`。
- HTTP 接口任务声明 `read` / `write` 权限但没有权限链路测试（router 注册 + 登录中间件 + 业务权限中间件），只写直接调用 controller handler → `severity=blocking`。
- 列表/查询任务没有“筛选字段测试矩阵”，或矩阵未逐项覆盖 TRD 请求字段、固定 WHERE、每个动态 WHERE、特殊语义、排序、分页、SELECT 字段裁剪和字段映射 → `severity=blocking`。
- Go Web data 层被规划为直接 import/接收 HTTP DTO，service 调用 `Build*Scope` / `Apply*Scope`，或 service/data 边界暴露 GORM scope、scope 参数、SQL builder / `*gorm.DB` 作为核心接口 → `severity=blocking`。
- Markdown 表格必须包含第二行分隔符；缺失导致表格不渲染 → `severity=major`。
- Go Web 后端任务必须对齐 `developer/references/goweb-file-creation-rules.md`：data 默认 `data/ds_/`，dto 默认 `dto/dto_/`，HTTP 协议测试不得放 `router/http__test.go`；若 Plan 使用历史偏差路径但没有 `goweb_path_confirmed` 和用户确认记录 → `severity=blocking`。

**D23 AIWeave Plan 字段与 docs/ 引用（仅 Go T1/T2 项目）**：
- 读取 `project_context_path` 或 TRD 同级/上级 `context.json`；若 `aiweave_status in {T1, T2}` 且 `project_path/go.mod` 存在，本检查必须执行。
- `plan_ir.tasks[]` 每个任务必须包含合法 `aiweave_skill`，取值只能是 `new-model / new-service / new-controller / new-router / new-middleware / new-scheduled-task / new-mq-consumer / new-test / new-saga-step`；缺失或非法 → `severity=blocking`。
- `plan_ir.tasks[]` 每个任务必须包含非空 `aiweave_docs_refs`，且每个 `docs/...md#anchor` 的文件部分必须在 `project_path/docs/` 下真实存在；缺失或路径不存在 → `severity=blocking`。**ref 字符串只允许 `path` 或 `path#anchor` 字面**，**禁止**夹带中文 `（…）` / 英文 `(...)` 备注（如 `docs/x.md（待开发追加）`）；备注请挪到任务的 `description` / `notes`。preflight 会以 `AIWEAVE_DOCS_REF_HAS_INLINE_NOTE` 报 `blocking`。
- `plan_ir.tasks[]` 每个任务必须包含 `build_status_target: 🟢`；缺失 → `severity=major`。
- `plan_ir.tasks[]` 每个任务必须包含 `red_tests`，至少 4 条，并覆盖正向 / 参数校验 / 业务错 / 副作用四类；不足或缺类 → `severity=blocking`。
- 任务拆分必须按 docs/ 模块边界 + AIWeave Skill 类型双重切分；一个 Txx 同时跨两种 `aiweave_skill` 类型或引用大量无关 docs 章节 → `severity=major`。
- markdown 任务章节必须渲染对应的 `aiweave_skill` 与 `aiweave_docs_refs`，否则 Developer 入场时无法知道该按哪个 vendor skill 和 docs 蓝图执行 → `severity=major`。

**如果 `project_path` 非空**，主动用 Grep/Read 检查：

**D4 路由风格一致性**：
- 从 plan 中找出接口路径格式（如 `/api/v1/xxx`）
- 用 Grep 在 project_path 下找现有路由注册方式（如 `router.GET`、`r.POST`）
- 如果 plan 里的路径格式与项目现有风格不一致 → `severity=major`
- 给出"项目实际路由格式示例" + "建议改成的格式"

**D5 错误码范围一致性**：
- Grep 项目中已用的错误码范围（如 `10001`-`10999`）
- 检查 plan 中定义的新错误码是否在合理的未占用范围
- 冲突 → `severity=major`

**D6 依赖包/框架调用方式**：
- plan 中提到的框架调用（如 `c.JSON`、`ctx.Bind`）是否与项目实际使用的框架一致
- 不一致 → `severity=major`，给出项目实际用法示例

**D7 目录/包命名风格**：
- plan 中提到的文件路径/包名是否符合项目命名风格（snake_case vs camelCase 等）
- 不一致 → `severity=minor`
- 对 Go Web 强规则，`data/`、`dto/`、`router/http__test.go` 不是普通风格差异；未记录用户确认的兼容偏差时必须 blocking。

**D11 DAO / Model / 数据访问风格一致性**：
- Read/Grep 项目已有 data/model/dao 代码，识别表名常量、TableName/getTable、BuildWhere/repository/transaction 等真实模式
- plan 如果另造一套 DAO/Model 风格，或没有说明应沿用的项目模式 → `severity=major`

**D12 明确决策与禁止暧昧二选一**：
- 检查 plan 是否出现「命名自定 / 后续约定 / 以实现时为准 / A 或 B / TBD / 待定」
- 错误码、常量、协议返回方式、依赖隔离方式必须明确
- 命中暧昧写法 → `severity=major`；影响 TDD 或接口协议时 → `severity=blocking`

**D16 AI 知识库回源查证**：
- 当 TRD 提到某项技术能力、外部依赖、数据同步方式、接口封装或测试替换点，但 `project_path` 当前代码现场找不到直接实现时，不要立刻判定为缺失。
- 先读取 `context.json`（或未来 `contexts.json`）中的 `knowledge_base_dirs` / `kb_paths` 等 AI 知识库路径；如果 dispatch 未显式传入，则从 `trd_path` 同级或上级 workspace 目录查找。
- 到关联 KB 中查找历史实现、客户端封装、连接方式、mock/替换点；找到线索后，再回到代码仓库按 KB 指向的路径/符号核对。
- 若 KB 有线索但 plan 未写明采用方式或代码落点 → `severity=major`；影响接口协议、数据一致性或 TDD 可执行性 → `severity=blocking`。
- 若代码与 KB 都找不到，plan 必须在 `STATUS.md` 阻塞项登记；未登记 → `severity=major`。

**D17 代码落地文件闭环**：
- 从 TRD 和 plan 中列出每个新增机制：权限、中间件、配置结构体、错误码、表名常量、外部依赖封装、日志审计、回滚、容量限制、降级策略等。
- 逐项检查它是否同时出现在文件清单、实现点 → 测试用例映射、RED 测试用例中。
- 缺任一环 → `severity=major`；影响接口协议、数据写入、安全权限、回滚一致性或 TDD 可执行性 → `severity=blocking`。

**D18 代码对账逐项核对**：
- 对照项目代码逐项检查：错误码、配置结构体、middleware、中间件顺序、表名常量/模型方法、全局外部依赖（DB/Redis/ES/MQ/HTTP client/文件存储等）。
- plan 只写“与项目风格一致”但不给具体对账结论，或漏掉关键类别 → `severity=major`。

**D19 外部依赖测试替换点**：
- 如果 plan 写了 mock DB/Redis/ES/MQ/HTTP client/文件存储等外部依赖，必须说明真实可替换接口、函数变量、gateway 封装、测试库或最小集成测试方案。
- 如果当前代码没有替换点，plan 必须先规划新增封装，或在 `STATUS.md` 阻塞项登记。
- 外部依赖无法替换导致 RED 测试不可执行 → `severity=blocking`。

**D20 横切章节与 HTTP 协议层测试**：
- 对照 TRD 后半部分和横切章节，检查权限、日志、审计、性能、容量、回滚、降级、监控等是否落到具体 Txx 任务。
- 每个 HTTP 接口至少要有一条 controller/httptest/协议层测试，覆盖路由、参数绑定、中间件顺序和响应外壳；只测 service → `severity=major`。
- 权限、上传下载、写接口回滚、响应协议等关键 HTTP 行为缺协议层测试 → `severity=blocking`。

**D21 PRD/TRD/KB/目标代码三位一体**：
- 读取 `project_context_path` 后，如果存在 `prd_path`，必须把 PRD 关键需求点与 TRD/Plan 对齐；如果 PRD 路径缺失，检查 Plan 是否说明缺失原因。
- Plan 必须有六列对齐矩阵：PRD 需求点 → TRD 落点 → KB 证据 → 目标代码落点 → Plan 任务 → RED 测试。缺失 → `severity=blocking`。
- 对每个被 TRD/Plan 使用的 KB 证据，检查是否归类为 `逻辑参考` / `边界控制` / `外部依赖参考` / `不采用`。只写“参考 AI 知识库” → `severity=blocking`。
- 逻辑参考：必须说明借鉴的业务逻辑、目标项目实现文件、对应测试；否则 `major`，影响数据一致性/接口协议时 `blocking`。
- 边界控制：必须说明源 AI 知识库项目中禁止照搬的目录、包名、CLI 任务、全局变量、部署假设，以及目标项目等价落点；缺失 → `major`。
- 外部依赖参考：DB/ES/Redis/MQ/HTTP client、表名、索引名、连接池、配置项等必须映射到目标项目代码落点或明确由本任务新增封装；真实 IP / 连通性 / conf yaml 实值不属于 Plan reviewer 阻塞项。
- 如果 PRD/TRD/KB/目标代码在字段、错误码、协议、资源名、数据一致性策略上冲突，而 Plan 自行拍板或绕过 → `blocking`。

### Step 4 · TDD 合规检查（D8-D14，最高优先级）

> **Z-Agent 重点检查项**：本步骤优先级高于代码风格类问题。只要 RED/GREEN/REFACTOR 闭环不完整，先登记 blocking issue；同时不要被“接口已覆盖”迷惑，D17-D22 的代码落地闭环、外部依赖替换点、横切章节、HTTP 协议层测试、IR 可执行性和 PRD/TRD/KB/目标代码三位一体也必须重点查。

**D8 测试规格在实现之前**（核心 TDD 检查）：
- 逐一检查每个接口章节：测试规格（`### 测试规格` 或等价标题）是否出现在「核心流程」/「实现步骤」之前
- 顺序颠倒 → `severity=blocking`（违反 TDD 铁律）
- 给出 `fix_type: str_replace`，old_text 为当前章节开头，new_text 为调整后顺序

**D9 测试规格可执行性**：
- 测试规格章节是否有：测试文件路径 + 测试用例表格（输入/输出）+ 运行命令
- 只写了"需要编写测试"这种空话 → `severity=major`
- 如果测试依赖 DB/ES/外部服务/multipart/binary stream/MQ/定时任务，但没有说明 mock 替换点、测试 DB、httptest、可替换依赖或协议层测试方式 → `severity=major`

**D13 RED/GREEN/REFACTOR 闭环完整性**：
- 逐一检查每个 Txx / FE-xx 任务章节是否存在 `RED`、`GREEN`、`REFACTOR` 三段，且顺序正确
- RED 必须说明测试文件、测试用例、运行命令、预期失败原因
- GREEN 必须说明最小实现范围，不允许把重构或额外需求塞进 GREEN
- REFACTOR 必须说明重构动作，以及重构后复跑同一批测试的命令
- 缺任一段、顺序错误、或 REFACTOR 只有口号没有验收命令 → `severity=blocking`

**D14 实现点 → 测试用例映射**：
- 每个任务必须有映射表，列出关键实现点及对应测试用例
- 文件清单里的关键实现点如果没有任何测试用例覆盖 → `severity=major`
- 接口协议、数据写入、权限、上传下载、MQ/定时任务等关键行为无测试映射 → `severity=blocking`

**D15 写入小块化合规**：
- 检查 plan 是否先写 `plan_ir.json`，再按任务/接口/流程拆成可局部替换的小节，避免后续修复必须整文件重写
- 如果 plan 中出现「一次性生成完整文件 / 文件太大直接整文件重写 / 后续整体替换」等执行痕迹 → `severity=major`
- 如果单个任务章节混入多个无关接口或流程，导致无法按小节修复 → `severity=major`

### Step 5 · 计划内部一致性（D10）

**D10 任务 ID 一致性**：
- README.md 的任务列表、STATUS.md 的任务状态、tdd_audit 表、任务文件的文件名
- 四者的任务 ID 应一致，不应有孤立任务
- tdd_audit 必须包含 `red_verified`、`green_verified`、`refactor_verified`、`output_hash`
- 不一致 → `severity=major`

### Step 6 · 登记 issues

每条 issue 包含（严格按 schema）：

```json
{
  "id": "iss-001",
  "severity": "blocking",
  "hard_gate_id": "D1",
  "location": {
    "file": "02_interfaces.md",
    "section": "接口一览",
    "snippet": "（相关原文 ≤120 字）"
  },
  "issue": "为什么是问题（不要只贴原文）",
  "suggested_fix": "具体怎么改",
  "fix_type": "str_replace",
  "old_text": "（当前内容，可执行 StrReplace 替换）",
  "new_text": "（修复后内容）"
}
```

### Step 7 · 决策 approved

- 存在任何 `blocking` → `approved=false`
- 存在任何 `major` → `approved=false`
- 只有 `minor` 或零 issue → `approved=true`

### Step 8 · 写出报告（**最关键的一步，绝不能忘**）

**必须**用 `Write` 工具把 JSON 写到 `reviewer_output_path`（绝对路径，覆盖写）。

报告顶层必须包含：
- `reviewer_runtime: "subagent"`
- `degraded: false`
- `dispatch_id: `

禁止写 `reviewer_runtime=session/current/manual`。如果你不是被独立子 Agent 派发，而是在主会话里看到这些指令，必须停止，不要伪造报告。

⚠️ 铁律：只在对话里打印 JSON 不算交付。**没落盘 = 整次评审作废**，会被主 Agent 重派一次（且 prompt 顶部会明确指责「上一轮你忘了写文件」）。

最终回复一句话：`已写入 ，approved=，issues=`

---

## 禁区

- 禁止修改 plan 文件本体
- 禁止生成新的 plan 章节/任务文件
- 禁止回复"整体不错""基本合理"这种笼统结论
- 禁止调用生成类 skill

## 输出样板

```json
{
  "approved": false,
  "reviewer_skill": "plan-from-trd-reviewer",
  "reviewer_skill_version": "1.0",
  "reviewer_runtime": "subagent",
  "degraded": false,
  "dispatch_id": "dispatch-id-from-input",
  "summary": "preflight 通过；语义层发现 1 blocking：POST /xxx/create 接口在 plan 中未覆盖；2 major：测试规格在核心流程之后（违反 TDD）+ 路由路径与项目风格不一致",
  "issues": [
    {
      "id": "iss-001",
      "severity": "blocking",
      "hard_gate_id": "D1",
      "location": { "file": "02_interfaces.md", "section": "接口一览", "snippet": "接口列表..." },
      "issue": "TRD §3.2 定义的 POST /xxx/create 接口在 plan 中完全未出现，AI 执行时无法找到对应任务",
      "suggested_fix": "在 02_interfaces.md 中追加「接口 N：POST /xxx/create」章节，包含测试规格 + 核心流程 + 实现步骤",
      "fix_type": "append",
      "old_text": "",
      "new_text": "## 接口 N：POST /xxx/create\n\n### 测试规格\n...\n\n### 核心流程\n...\n\n### 实现步骤\n..."
    }
  ],
  "unresolvable_notes": []
}
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xurb-nexus](https://github.com/xurb-nexus)
- **Source:** [xurb-nexus/nexus-harness](https://github.com/xurb-nexus/nexus-harness)
- **License:** Apache-2.0
- **Homepage:** https://xurb-nexus.github.io/nexus-harness/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-xurb-nexus-nexus-harness-plan-from-trd-reviewer
- Seller: https://agentstack.voostack.com/s/xurb-nexus
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.