@openprd/cli 0.1.19 → 0.1.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/.openprd/changes/openprd-control-plane-v020/.openprd.yaml +2 -0
  2. package/.openprd/changes/openprd-control-plane-v020/design.md +78 -0
  3. package/.openprd/changes/openprd-control-plane-v020/proposal.md +54 -0
  4. package/.openprd/changes/openprd-control-plane-v020/specs/agent-requirements/spec.md +16 -0
  5. package/.openprd/changes/openprd-control-plane-v020/task-events.jsonl +27 -0
  6. package/.openprd/changes/openprd-control-plane-v020/tasks-002.md +35 -0
  7. package/.openprd/changes/openprd-control-plane-v020/tasks.md +427 -0
  8. package/.openprd/changes/remove-session-tracking-humane-approval/.openprd.yaml +2 -0
  9. package/.openprd/changes/remove-session-tracking-humane-approval/design.md +52 -0
  10. package/.openprd/changes/remove-session-tracking-humane-approval/proposal.md +35 -0
  11. package/.openprd/changes/remove-session-tracking-humane-approval/specs/agent-requirements/spec.md +16 -0
  12. package/.openprd/changes/remove-session-tracking-humane-approval/task-events.jsonl +1 -0
  13. package/.openprd/changes/remove-session-tracking-humane-approval/tasks.md +170 -0
  14. package/.openprd/design/active/asset-spec.md +19 -14
  15. package/.openprd/design/active/direction-plan.md +19 -3
  16. package/.openprd/design/active/facts-sheet.md +16 -7
  17. package/.openprd/design/active/image-preflight.md +6 -5
  18. package/.openprd/design/active/review-studio-v020-directions/compare-plan.json +34 -0
  19. package/.openprd/design/active/review-studio-v020-directions/contact-sheet.jpg +0 -0
  20. package/.openprd/design/active/review-studio-v020-directions/crops/01.png +0 -0
  21. package/.openprd/design/active/review-studio-v020-directions/crops/02.png +0 -0
  22. package/.openprd/design/active/review-studio-v020-directions/crops/03.png +0 -0
  23. package/.openprd/design/active/review-studio-v020-directions/focus-board.template.json +69 -0
  24. package/.openprd/design/active/review-studio-v020-directions/parallel-board.template.json +45 -0
  25. package/.openprd/design/active/review-studio-v020-directions/reference-set.json +143 -0
  26. package/.openprd/design/active/review-studio-v020-directions/source.png +0 -0
  27. package/.openprd/design/active/selected-direction.md +23 -9
  28. package/.openprd/engagements/active/control-plane-architecture.json +203 -0
  29. package/.openprd/engagements/active/control-plane-intake.json +418 -0
  30. package/.openprd/engagements/active/prd.md +183 -119
  31. package/.openprd/engagements/active/review-presentation-v0018.json +176 -0
  32. package/.openprd/i18n-config.json +12 -0
  33. package/.openprd/ledger/events.jsonl +6 -0
  34. package/.openprd/ledger/heads/ebea1a71a9daa566f1c91b53.json +10 -0
  35. package/.openprd/manifest.json +21 -0
  36. package/AGENTS.md +7 -6
  37. package/README.md +31 -29
  38. package/README_EN.md +36 -39
  39. package/package.json +1 -1
  40. package/skills/openprd-frontend-design/SKILL.md +16 -0
  41. package/skills/openprd-harness/SKILL.md +7 -7
  42. package/skills/openprd-quality/SKILL.md +1 -1
  43. package/skills/openprd-requirement-intake/SKILL.md +1 -1
  44. package/skills/openprd-shared/SKILL.md +6 -6
  45. package/src/adapters/adapter-spi.js +193 -0
  46. package/src/adapters/capability-envelope.js +98 -0
  47. package/src/adapters/event-normalizer.js +55 -0
  48. package/src/adapters/index.js +4 -0
  49. package/src/adapters/install-safety.js +249 -0
  50. package/src/agent-canonical-content.js +4 -2
  51. package/src/agent-integration.js +169 -46
  52. package/src/cli/args.js +63 -4
  53. package/src/cli/gate-print.js +17 -0
  54. package/src/cli/quality-commands.js +18 -0
  55. package/src/cli/quality-print.js +10 -0
  56. package/src/cli/runtime-print.js +24 -0
  57. package/src/codex-hook-runner-template.mjs +129 -199
  58. package/src/codex-runtime.js +48 -5
  59. package/src/context/cache.js +245 -0
  60. package/src/context/compiler.js +438 -0
  61. package/src/context/constants.js +30 -0
  62. package/src/context/index.js +39 -0
  63. package/src/context/redaction.js +84 -0
  64. package/src/context/stable.js +69 -0
  65. package/src/context/telemetry.js +42 -0
  66. package/src/dev-standards.js +57 -0
  67. package/src/fleet.js +112 -95
  68. package/src/gates/index.js +2 -0
  69. package/src/gates/scoped-gates.js +256 -0
  70. package/src/gates/store.js +126 -0
  71. package/src/gates/workspace.js +41 -0
  72. package/src/html-artifacts.js +725 -28
  73. package/src/kernel/atomic-store.js +299 -0
  74. package/src/kernel/event-envelope.js +166 -0
  75. package/src/kernel/index.js +4 -0
  76. package/src/kernel/project-ledger.js +467 -0
  77. package/src/kernel/project-manifest.js +205 -0
  78. package/src/knowledge-v3/index.js +1 -0
  79. package/src/knowledge-v3/lifecycle.js +290 -0
  80. package/src/knowledge.js +14 -7
  81. package/src/openprd.js +71 -2
  82. package/src/review-model.js +413 -0
  83. package/src/review-presentation.js +1 -1
  84. package/src/run-harness.js +432 -38
  85. package/src/runtime/cli_runtime_README.md +28 -0
  86. package/src/runtime/errors.js +66 -0
  87. package/src/runtime/index.js +44 -0
  88. package/src/runtime/lane-schema.js +141 -0
  89. package/src/runtime/lane-store.js +279 -0
  90. package/src/runtime/task-runtime.js +449 -0
  91. package/src/runtime/workspace.js +179 -0
  92. package/src/runtime/write-set.js +206 -0
  93. package/src/session-binding.js +16 -3
  94. package/src/session-registry.js +59 -1
  95. package/src/upgrade/fleet-mutation.js +166 -0
  96. package/src/upgrade/fleet-transaction.js +398 -0
  97. package/src/upgrade/transaction-store.js +416 -0
  98. package/src/visual-compare-core.js +66 -27
  99. package/src/visual-compare.js +18 -12
  100. package/src/workspace-core.js +109 -7
  101. package/src/workspace-registry.js +39 -1
  102. package/src/workspace-workflow.js +18 -15
@@ -0,0 +1,10 @@
1
+ {
2
+ "schema": "openprd.stream-head",
3
+ "version": 1,
4
+ "projectId": "project_a63099e6-6438-424c-ac39-49337f485ede",
5
+ "streamId": "workflow:workspace",
6
+ "revision": 6,
7
+ "lastEventId": "evt_19b2167661a74c24174705119098e339",
8
+ "ledgerPosition": 6,
9
+ "updatedAt": "2026-07-11T11:23:43.123Z"
10
+ }
@@ -0,0 +1,21 @@
1
+ {
2
+ "schema": "openprd.project-manifest",
3
+ "schemaVersion": 1,
4
+ "projectId": "project_a63099e6-6438-424c-ac39-49337f485ede",
5
+ "createdAt": "2026-07-10T15:49:37.742Z",
6
+ "compatibility": {
7
+ "minimumReaderVersion": 1,
8
+ "minimumWriterVersion": 1
9
+ },
10
+ "formats": {
11
+ "eventEnvelope": 1,
12
+ "ledger": 1,
13
+ "projection": 1,
14
+ "contextCapsule": 1,
15
+ "taskRuntime": 1,
16
+ "scopedGate": 1,
17
+ "reviewModel": 1,
18
+ "knowledge": 3,
19
+ "adapter": 1
20
+ }
21
+ }
package/AGENTS.md CHANGED
@@ -28,11 +28,12 @@
28
28
  1a. 互动或显式启用 OpenPrd 的场景,再从 `.openprd/` 重建状态,并先运行 `openprd run . --context`;它是建议上下文,不是自动执行指令。
29
29
  1a. 代码搜索默认从当前任务相关源码、测试和 change/task 文件起步;不要把 `.openprd/quality/reports/`、`.openprd/harness/` 或 `.openprd/learning/` 当源码目录做 repo-wide `rg`。质量报告只在需要审阅就绪证据时按最新报告路径显式读取。
30
30
  2. 规划、分析、架构评审、“怎么改”或“会动哪些文件”类请求保持只读;只有用户明确要求实现、继续任务、深度调研、对标复刻或提交时才进入执行。
31
- 3. 先分流再执行:`openprd-requirement-intake` 按影响面、未知数、决策成本和验证成本判断需求类型,并保留内部路由码对照:直接处理=L0,现有功能优化=L1,新功能/新流程方案=L2。用户审查默认把路由码并进“需求类型:直接处理(L0)”这类标签里;只有内部排障确实受益时,才额外附“内部路由码”。直接处理类需求可直接处理并事后说明,不打开正式 PRD/review/change/tasks;现有功能优化先在对话内给 mini-plan 再执行,默认不生成正式 PRD/change/tasks;如果用户刚刚已经确认了 L1 mini-plan、范围边界或正式产品边界,后续承接要写成“已确认,我按这个继续”,不要用“确认,我们就按这个……”这类像再次索取确认的句子。只有新功能/新流程方案才先走 requirement intake、对话内 requirement 摘要确认,再 `review/change/tasks`,最后才实现。L2 的 requirement 摘要默认按“需求判断 / 需求理解 / 功能范围 / 技术方案”来写,其中“功能范围”和“技术方案”优先用 Markdown 表格,帮助用户一眼看清;`需求判断` 和 `需求理解` 先用 1 到 2 句轻量主句说清这次是什么、核心问题和第一版目标,边界、风险、异常例子和技术细节下沉到后面的分项或表格,不要把它们都塞进一整段长话里,也不要把某条示例文案写成固定模板。若当前仍在 0 到 1 探索、脑暴或值不值得做的判断,摘要里还要主动补上“验证与创业闭环”:第一批最容易触达的社区或种子用户、你为什么算这个社区里的自己人、当前替代方案和痛点证据、先怎么手工交付、手工作战卡怎么写、能不能先用 spreadsheet / 表单 / no-code 跑起来、如果必须开始做产品也只自动化最重复的一步并先压成 forms / lists / CRUD 骨架、第一版只做哪一件事、能不能压成周末级 MVP、第一批客户路径、从第一个客户开始怎么收费、客户 1 如何打平成本、有没有 10 个样本和更强付费信号、达到什么条件才允许产品化、增长阶段守什么纪律、这条路是否可逆、是否真在解决客户问题、以及是否符合团队价值观、是不是你愿意长期住进去的业务形态。L2 的首轮澄清只能承诺“我先整理需求摘要给你确认”,不能把 requirement 摘要确认、review 和实现压成一句“你回我一句我就开始实现”。如果 `openprd run . --context` 仍然建议 `clarify-user`,当前这轮回复的目标就只能是 `需求摘要` `1 个最高价值澄清点`,不要写成“我先按默认方案实现”。如果用户的下一条回复只是承接上一轮 requirement 摘要的短跟进,而不是提出新范围、改目标或重新发起分析请求,就把它当成对上一轮摘要、默认方向或选项的继续确认,不要重新开一轮泛化 clarify;应直接按当前对话上下文把已确认事实用 canonical capture 路径、`user-confirmed` 来源写回,而不是继续写 `agent-inferred/project-derived` 的用户澄清字段。单纯的“请帮我实现/继续实现”只表示有执行意图,不表示可以跳过 requirement 摘要确认、`capture/classify/synthesize` 写入路径或 review;只有用户明确表示“不需要进行任何确认”时,才允许静默走完整 requirement write path。`review.html` 是稳定评审 artifact,不再默认等于唯一的人类停顿点;默认按 decision-points approval policy 执行,只有当前 lane 仍要求人类决策时才在 final answer 主体里停下请求确认;当 review 已确认且 tasks 已就绪但还需要执行授权时,先给执行确认清单再请用户确认。
31
+ 3. 先分流再执行:`openprd-requirement-intake` 按影响面、未知数、决策成本和验证成本判断需求类型,并保留内部路由码对照:直接处理=L0,现有功能优化=L1,新功能/新流程方案=L2。用户审查默认把路由码并进“需求类型:直接处理(L0)”这类标签里;只有内部排障确实受益时,才额外附“内部路由码”。直接处理类需求可直接处理并事后说明,不打开正式 PRD/review/change/tasks;现有功能优化先在对话内给 mini-plan 再执行,默认不生成正式 PRD/change/tasks;如果用户刚刚已经确认了 L1 mini-plan、范围边界或正式产品边界,后续承接要写成“已确认,我按这个继续”,不要用“确认,我们就按这个……”这类像再次索取确认的句子。新功能/新流程方案的 requirement、PRD、review、change tasks Agent 在后台维护,不阻断用户已经要求的实现。L2 的 requirement 摘要默认按“需求判断 / 需求理解 / 功能范围 / 技术方案”来写,其中“功能范围”和“技术方案”优先用 Markdown 表格,帮助用户一眼看清;`需求判断` 和 `需求理解` 先用 1 到 2 句轻量主句说清这次是什么、核心问题和第一版目标,边界、风险、异常例子和技术细节下沉到后面的分项或表格,不要把它们都塞进一整段长话里,也不要把某条示例文案写成固定模板。若当前仍在 0 到 1 探索、脑暴或值不值得做的判断,摘要里还要主动补上“验证与创业闭环”:第一批最容易触达的社区或种子用户、你为什么算这个社区里的自己人、当前替代方案和痛点证据、先怎么手工交付、手工作战卡怎么写、能不能先用 spreadsheet / 表单 / no-code 跑起来、如果必须开始做产品也只自动化最重复的一步并先压成 forms / lists / CRUD 骨架、第一版只做哪一件事、能不能压成周末级 MVP、第一批客户路径、从第一个客户开始怎么收费、客户 1 如何打平成本、有没有 10 个样本和更强付费信号、达到什么条件才允许产品化、增长阶段守什么纪律、这条路是否可逆、是否真在解决客户问题、以及是否符合团队价值观、是不是你愿意长期住进去的业务形态。L2 的需求摘要是 Agent 后台维护材料,不创建用户确认停顿。如果 `openprd run . --context` 建议 `clarify-user`,Agent 优先选择可逆默认方案并显式说明假设;是否提问由 Agent 自行判断。如果用户的下一条回复只是承接上一轮 requirement 摘要的短跟进,而不是提出新范围、改目标或重新发起分析请求,就把它当成对上一轮摘要、默认方向或选项的继续确认,不要重新开一轮泛化 clarify;应直接按当前对话上下文把已确认事实用 canonical capture 路径、`user-confirmed` 来源写回,而不是继续写 `agent-inferred/project-derived` 的用户澄清字段。“请帮我实现/继续实现”表示执行意图;requirementcapture/classify/synthesize review Agent 在后台维护,不追加 OpenPrd 确认门禁。`review.html` 是稳定评审 artifact,不是授权门禁;Agent 自行记录并继续,OpenPrd 不要求用户批准评审稿或执行清单。
32
32
  4. change/tasks 就绪后,用 `openprd-test-strategy` 按风险选择单元、集成、端到端、人工、视觉、小程序、性能或安全验证组合,并在任务或报告中保留 evidence-plan;同时根据任务边界记录 execution strategy:小范围修正保持 `serial`,中等规模 L1/L2 可推荐 `parallel-workers`,高风险或大规模实现再升级到 `parallel-workers-isolated`;70/20/10 只作健康形状参考,不作硬门禁。
33
- 5. 纯图片、封面图、配图、海报、插画、图标、贴纸、mockup 或“先看样子”请求按生图路由选工具:先判断当前对话工具面,Codex 环境用原生 `imagegen`(Image 2),Cursor 环境用内置 `GenerateImage`,两者都是工具内免费能力;都不可用或无法判断时,先读 `.openprd/harness/image-generation-preference.json` 的用户已确认偏好,没有偏好就先问用户选哪种生图方式,并把答复以 `user-confirmed` 来源写回该文件作为下次默认;绝不擅自调用用户本地或自有付费生图 API。生图工具是工具路径,不是审美豁免,生成前先写清用途、受众、气质、约束和记忆点,并用 anti-slop 避免默认紫白/蓝紫渐变、通用字体、白底卡片堆叠和无语境装饰;其中 logo、icon、avatar、badge 等开发素材在用户未明确要求场景化展示时,默认按独立素材输出(standalone asset)生成:全画布单主体,不额外添加卡片、设备框或其他展示容器;只有实际发生生图工具调用后,才能汇报生图结果、失败或限流。生图结果先当候选效果图,不要默认登记到 `.openprd/harness/visual-reviews/`。Agent 要主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现;只有确认后,才把选定方向、整张图或其中子图整理成 reference-set 并进入实现。进入实现阶段时,已有确认参考图用 `openprd visual-compare --reference/--actual`;如果参考图是一张整板、网格图或多对象组合,先运行 `openprd visual-prepare --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`,确认 contact sheet 后再逐项对比;没有参考图时先判断新建界面还是修改既有界面,新建界面先按用户目标、信息架构变化、视觉决策成本和验证风险完成 3 方向方案评审,修改既有界面用 `openprd visual-compare --before/--after`;局部细节重点则补 `openprd visual-compare --board <focus-board.json>`,多方向实验则补 `openprd visual-compare --board <parallel-board.json>`;普通截图、Computer/Browser/Playwright 实测截图要作为证据时补 `openprd visual-compare --board <verification-board.json>`;同构列表、卡片、网格、表格或用户反馈没对齐时补 `openprd visual-compare --board <alignment-board.json>`,并同时覆盖容器轨道与内部内容槽位轨道;单个 logo、icon、avatar、badge、按钮图形或图片内部居中/视觉重心/偏心问题补 `openprd visual-compare --board <centering-board.json>`,并同时覆盖画布中心、主体外接框中心和视觉重心偏移。visual evidence 同时检查气质、层级、字体/色彩/表面角色和记忆点,不只检查截图是否存在。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”,不能只口头说对比过了,至少先产出一份视觉证据图。如果用户目标是把工作转成可学习、可复用、可回看、可教学或可沉淀的材料,先按期望产物是否需要章节结构、证据锚点、图文讲解、检索练习、工作示例或长期阅读体验来判断;需要时优先走 `openprd learn .` 生成学习包和阅读器,不要用关键词表触发;“仙侠风格的学习材料”这类短请求也按学习型交付物处理,风格只作为 `--genre` 题材参数。
34
- 5a. 对 logo、icon、avatar、badge、贴纸、空态插画、单物件 UI 位图等开发素材,如果最终要接入 UI 并需要透明背景,默认走“候选评审 -> 资产工程化 -> 接入验证”的图标资产链路:先基于用途、受众、气质、约束和记忆点生成 3 个差异足够大的独立素材候选方向,并保持纯 `#00ff00` 绿幕、无文字、无 UI 容器、主体居中且留足裁切边距;用户选定前不写入项目文件。用户选定后再定位源图或 contact sheet,保留绿幕源图,用 `remove_chroma_key.py` 抠成透明 PNG/WebP,按真实 UI 需要裁切居中并导出 384px 或多尺寸资产;接入时按首页卡片、工具格、吸顶栏、偏好预览等实际场景分别调显示比例,而不是只换图片路径。收口时同步写回 `.openprd/design/active/asset-spec.md` 和 `selected-direction.md`,说明选中的方向、资产路径、透明产物、接入位置和验证结果;最终回复必须区分绿幕源图、透明产物和是否已经接入。
33
+ 5. 纯图片、封面图、配图、海报、插画、图标、贴纸、mockup 或“先看样子”请求按生图路由选工具:先判断当前对话工具面,Codex 环境用原生 `imagegen`(Image 2),Cursor 环境用内置 `GenerateImage`,两者都是工具内免费能力;都不可用或无法判断时,先读 `.openprd/harness/image-generation-preference.json` 的用户已确认偏好,没有偏好就先问用户选哪种生图方式,并把答复以 `user-confirmed` 来源写回该文件作为下次默认;绝不擅自调用用户本地或自有付费生图 API。生图工具是工具路径,不是审美豁免,生成前先写清用途、受众、气质、约束和记忆点,并用 anti-slop 避免默认紫白/蓝紫渐变、通用字体、白底卡片堆叠和无语境装饰;其中 logo、icon、avatar、badge 等开发素材在用户未明确要求场景化展示时,默认按独立素材输出(standalone asset)生成:全画布单主体,不额外添加卡片、设备框或其他展示容器;只有实际发生生图工具调用后,才能汇报生图结果、失败或限流。生图结果先当候选效果图,不要默认登记到 `.openprd/harness/visual-reviews/`。Agent 应展示候选方向并说明采用的可逆默认方向;OpenPrd 不强制等待确认,用户明确选择时再覆盖默认方向并更新 reference-set。进入实现阶段时,已有确认参考图用 `openprd visual-compare --reference/--actual`;如果参考图是一张整板、网格图或多对象组合,先运行 `openprd visual-prepare --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`,确认 contact sheet 后再逐项对比;没有参考图时先判断新建界面还是修改既有界面,新建界面先按用户目标、信息架构变化、视觉决策成本和验证风险完成 3 方向方案评审,修改既有界面用 `openprd visual-compare --before/--after`;局部细节重点则补 `openprd visual-compare --board <focus-board.json>`,多方向实验则补 `openprd visual-compare --board <parallel-board.json>`;普通截图、Computer/Browser/Playwright 实测截图要作为证据时补 `openprd visual-compare --board <verification-board.json>`;同构列表、卡片、网格、表格或用户反馈没对齐时补 `openprd visual-compare --board <alignment-board.json>`,并同时覆盖容器轨道与内部内容槽位轨道;单个 logo、icon、avatar、badge、按钮图形或图片内部居中/视觉重心/偏心问题补 `openprd visual-compare --board <centering-board.json>`,并同时覆盖画布中心、主体外接框中心和视觉重心偏移。visual evidence 同时检查气质、层级、字体/色彩/表面角色和记忆点,不只检查截图是否存在。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”,不能只口头说对比过了,至少先产出一份视觉证据图。如果用户目标是把工作转成可学习、可复用、可回看、可教学或可沉淀的材料,先按期望产物是否需要章节结构、证据锚点、图文讲解、检索练习、工作示例或长期阅读体验来判断;需要时优先走 `openprd learn .` 生成学习包和阅读器,不要用关键词表触发;“仙侠风格的学习材料”这类短请求也按学习型交付物处理,风格只作为 `--genre` 题材参数。
34
+ 5a. 对 logo、icon、avatar、badge、贴纸、空态插画、单物件 UI 位图等开发素材,如果最终要接入 UI 并需要透明背景,默认走“候选评审 -> 资产工程化 -> 接入验证”的图标资产链路:先基于用途、受众、气质、约束和记忆点生成 3 个差异足够大的独立素材候选方向,并保持纯 `#00ff00` 绿幕、无文字、无 UI 容器、主体居中且留足裁切边距;Agent 可先保留候选源图并选择可逆默认方向;用户明确选定时优先采用。进入资产工程化后再定位源图或 contact sheet,保留绿幕源图,用 `remove_chroma_key.py` 抠成透明 PNG/WebP,按真实 UI 需要裁切居中并导出 384px 或多尺寸资产;接入时按首页卡片、工具格、吸顶栏、偏好预览等实际场景分别调显示比例,而不是只换图片路径。收口时同步写回 `.openprd/design/active/asset-spec.md` 和 `selected-direction.md`,说明选中的方向、资产路径、透明产物、接入位置和验证结果;最终回复必须区分绿幕源图、透明产物和是否已经接入。
35
35
  5b. 卡片宽度、间距、留白、对齐、颜色、圆角、字号、按钮或图标等轻量 UI 可视优化,仍可按 L0/L1 小范围修正推进,不自动升级成大界面 3 方向方案评审;但它是用户可见变化,动手前要有一句审美意图和记忆点,收口必须补 `visual-compare` 修改前后图、局部焦点证据板、截图实测证据板、对齐辅助线证据板或内部居中证据板,并检查气质、层级、颜色、字号、间距和表面角色是否成立。只要界面里有同构列表、卡片、网格或表格,就把容器轨道以及标题、副标题、描述、标签、状态、价格、按钮、图标、操作区等相同文案类型/相同组件槽位的对齐当作默认验收项,不等用户先投诉;只量外框、列宽或行顶不算完整对齐验收。只要任务在判断单个素材/图标/头像/徽标/按钮图形的内部居中、偏心或视觉重心,就把 centering-board 当作默认验收项;单张原始截图或主观“看起来居中”不算完整居中验收。build、package、`openprd dev-check` 和单张原始截图不能替代视觉证据。`visual-compare` 每次都会返回 `chatEmbed` markdown;生成证据板后必须把这行 `![视觉证据: ...](路径)` 直接嵌入最终回复,让证据在对话流里可见,不要只报告文件路径;`openprd dev-check` 在触达界面文件且最近 24 小时没有证据板时也会输出视觉证据提醒,收口前按提醒补齐。
36
+ 5c. 大界面三方向是 Agent 的默认责任,不要求用户另行提出生图;轻量 UI 微调不触发。已有界面时,Codex 原生 App 用 Computer Use、Codex 网页环境用 Chrome 插件任务专用窗口、Cursor 用可用浏览器或项目预览能力截图;三个方向必须共享同一张当前截图作为 image-to-image 参考。除非用户明确要求换风格,否则锁定字体角色、色彩系统、明暗模式、表面语言、圆角/边框/阴影、图标语言、平台框架和信息密度,只探索布局、信息层级、导航、关键路径与空间构图。冷启动没有现有界面时才使用 design brief,不伪造修改前截图。候选图先明确用途、目标用户、业务约束、核心动作、气质和唯一记忆点,并检查字体、色彩、空间、层级、表面/图标语言和动效含义;拒绝无依据蓝紫渐变、默认字体、等权白卡堆叠、过量大圆角、无语境装饰和只换颜色的伪方向。
36
37
  6. 界面、页面、视觉、样式、信息架构或前端体验任务进入实现前,先读取 `$openprd-frontend-design`,并用 `.openprd/design/active/` 补齐 `facts-sheet / asset-spec / image-preflight / direction-plan / selected-direction`;空白工作区优先从 `.openprd/design/templates/` 选最近模板。若用户已经给了效果图、设计稿、参考截图或其他明确参考图,先把它当成主参考源;只有现有 starter、theme、layout 足够接近时才复用,不接近就允许偏离默认组合,以参考图为准。若当前轮用户已经把页面主题、模块范围或“直接实现”的意图说清,优先运行 `openprd run . --context --message <用户原话>`。若页面主题和模块范围已经明确,优先运行 `openprd design-starter . --starter <starter-id> --out index.html --brief "<页面主题>" --sections "<模块1|模块2|模块3>"` 起第一版真实页面;只有这个页面本来就不依赖外部产品事实、品牌素材或真实图片时,才在 active design artifacts 写清无依赖并补 `--no-external-facts --no-brand-assets --no-real-images`;若题目更像旅游、导览、展览、博物馆、城市、自然观察或案例内容页,先不要带 `--no-real-images`,让 starter 先尝试补首批真实图片;若这类冷启动即使带 message 仍短暂返回 `clarify-user`,把它当成摘要级提醒,先用 3 到 5 行 mini-plan 收口,再继续。starter 落地后默认进入 `Patch Mode`,必须直接在生成的入口文件上补丁修改;即使结构要大改,也是在同一路径内覆盖,不做 delete-first,更不要删除 `index.html` 后另起新稿。如果确实要整页重写,先把完整新稿写到 sibling draft,例如 `index.next.html`,确认内容成形后再覆盖回 `index.html`,不要让正式入口出现空窗;starter 一落地后,只允许做一轮就地对焦:快速读一次生成的入口文件和必要的 active design artifacts;这轮对焦结束后,下一步就必须是真实写入口,不要再回头搜网页、翻 `docs/basic/` 或继续模板漫游;把最后一批必要的查事实、查图、读模板动作放在口头宣布之前做完;一旦已经说“开始覆盖入口文件”或“开始整页重写”,下一步必须出现真实写文件动作,而不是继续只读浏览、压图或停在口头承诺;必要时 hook 会把这类非写入动作挡回去;`Patch Mode` 完成不等于只补合同、只下载素材或只写计划;至少要把入口文件本体改完、主要占位清掉,并把已准备好的真实图片或参考约束真正落进页面;没有明确参考方向时,不要直接落回同一种安全极简解。
37
38
  6a. 写产品界面上用户能看到的文案时,必须站在当前用户视角写:这句话要说明用户现在能做什么、会发生什么、为什么值得点、下一步怎么走。除非这是面向开发者或专业技术人员的技术型产品,否则默认用普通人能看懂的语言写结果、状态、限制和行动,不要暴露 API、SDK、模型、数据库、缓存、错误码或内部模块。正反例:不要写“适合想保留全部工具入口的用户”,改写成“首页会显示所有工具入口,你可以直接选择需要的功能”;不要写“API 请求失败,错误码 500”,改写成“暂时保存失败,请稍后再试”;技术型产品可以保留必要术语,但仍要写清用户动作、影响和修复路径。
38
39
  6b. 开发新功能出现新的入口、按钮、tab、卡片、空态或工具格时,默认自动配图标,不等用户提出:先复用项目已有图标体系;项目没有时按图标最佳实践路由选型(UI 图标 Phosphor,落码 Lucide/Tabler/React Icons,AI 品牌 LobeHub Icons,技术栈 Tech Icons,功能图标/插画 iconfont),把图标名、来源、用途登记到 `.openprd/design/active/asset-spec.md` 的“功能图标”行再接入。只有语义确实不需要图标或用户明确说不要时才跳过,并在收口说明原因。
@@ -45,11 +46,11 @@
45
46
  ### Hook-Enforced Gates
46
47
 
47
48
  - automation-safe:识别到 Codex automation、Claude Code headless、cron、scheduled 或 unattended task 时,hook 默认不注入 OpenPrd context、不阻断写入、不要求 dev-check / quality / doctor;只有 OpenPrd 维护任务或显式启用 OpenPrd 时才恢复这些门禁。
48
- - requirement:需求未完成 `clarify/review/change/tasks` 前阻断实现写入;tasks 就绪后,只有用户原始意图已明确要求实现,或后续在看过执行确认清单后明确发出执行指令时才放行。
49
+ - requirement:requirement、PRD、reviewchange tasks 是 Agent 后台维护材料,不阻断实现、不索取用户确认。
49
50
  - research:公开 GitHub 架构/对标先 DeepWiki;第三方技术用法、配置、限制、版本差异或迁移先查本地证据,不足时再按 `resolve_library_id -> query_docs` 使用 Context7。
50
51
  - design:界面、页面、视觉和前端体验任务进入实现前,先读取 `$openprd-frontend-design`,并补齐 `.openprd/design/active/` 下的事实、素材、图片和方向合同。
51
- - skill-visualization:修改 skill、`SKILL.md`、`AGENTS.md` 或相关 workflow 前,先输出彩色 Mermaid 方案并等待用户确认。
52
- - autonomy-risk:即使已经授权实现,也默认阻断未经当前用户明确批准的云端热修复、生产远端写入、业务兜底、写死逻辑、客户端/服务端补业务数据或缓存补行。
52
+ - skill-visualization:修改 skill、`SKILL.md`、`AGENTS.md` 或相关 workflow 前,用彩色 Mermaid 说明方案;它是可视说明,不是用户授权门禁,用户已要求修改时可继续执行。
53
+ - autonomy-risk:风险识别只向 Agent 提供配置化、迁移、标准状态机、幂等脚本和可回滚发布路径建议,不承担授权审批;OpenPrd 不因生产、支付、删除、账号切换、兜底、写死或材料缺失阻断工具调用,也不索取用户确认,是否需要确认由当前 Agent 依据宿主安全规则和真实上下文自行判断。
53
54
  - secrets / weapp / browser / copy:分别处理 `secrets-vault`、按需的小程序运行态验证、窗口归属与 i18n/普通用户文案提醒。
54
55
  - 需要细节时,读 router 指向的 skill 和 command catalog,而不是继续扩写 `AGENTS.md`。
55
56
 
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  简体中文 | [English](./README_EN.md)
4
4
 
5
- > 帮团队先把需求说清楚、确认清楚,再更稳地交付的 AI 原生 PRD 工作区与 CLI。
5
+ > 帮团队和 Agent 把需求说清楚、持续做下去并用证据交付的 AI 原生 PRD 工作区与 CLI。
6
6
 
7
7
  [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
8
8
  [![Node.js](https://img.shields.io/badge/node-%3E%3D20.19.0-339933.svg)](https://nodejs.org/)
@@ -11,12 +11,19 @@
11
11
  OpenPrd 是一个轻量但结构化的 **PRD harness**。你只需要先把问题说出来,它会帮团队和 Agent 把需求整理成:
12
12
 
13
13
  - 需求澄清
14
- - 用户确认
14
+ - Agent 后台维护的需求事实与决策记录
15
15
  - 图形化评审
16
- - 冻结前关卡控制
16
+ - 非阻断式风险提醒与交付检查
17
17
  - 面向执行系统的结构化交接
18
18
 
19
- 它把关键确认点沉淀成稳定的 HTML 产物,而不是把版本状态散落在聊天记录或终端输出里。
19
+ 它把需求、决策和验证结果沉淀成稳定的 HTML 产物,而不是把状态散落在聊天记录或终端输出里。OpenPrd 的职责是帮助 Agent 做事:PRD、review、change、tasks、设计合同与测试证据由 Agent 在后台维护,不再要求用户回复指定内容才能继续。
20
+
21
+ ## 0.1.22:不再把流程材料变成用户门禁
22
+
23
+ - OpenPrd 不再因需求摘要、评审稿、设计合同、测试证据或风险分类缺失而阻断实现。
24
+ - 生产、支付、删除、账号切换、兜底与写死等信号只给 Agent 安全建议,不由 OpenPrd 索取用户确认。
25
+ - Skill / AGENTS 方案图和大界面候选方向用于帮助理解,不再成为写入或实现授权门槛。
26
+ - Codex、Claude Code、Cursor 共用同一套“Agent 后台维护、用户任务优先”的规则。
20
27
 
21
28
  ![OpenPrd 能力总览](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-capability-overview-zh.png)
22
29
 
@@ -25,7 +32,7 @@ OpenPrd 是一个轻量但结构化的 **PRD harness**。你只需要先把问
25
32
  如果你希望:
26
33
 
27
34
  - 在写 PRD 前先澄清需求
28
- - 区分用户确认、项目已有事实和 Agent 推断
35
+ - 区分用户原始表达、项目已有事实和 Agent 推断
29
36
  - 在 freeze 前插入架构图 / 流程图评审
30
37
  - 让 Agent 遵循 repo 内置的协同规则
31
38
 
@@ -52,12 +59,12 @@ OpenPrd 解决的问题,不只是“把 spec 写出来”,也不只是“把
52
59
 
53
60
  | 工具 | 重心 | 用户主要看到的产物 | 更适合什么 |
54
61
  |------|------|--------------------|------------|
55
- | **OpenPrd** | 需求澄清、HTML 优先协作、交付门禁 | `review.html`、学习阅读器、质量报告、图示、结构化 change/task 状态 | 需要把人机协同、评审确认、执行推进和交付判断串起来的团队 |
62
+ | **OpenPrd** | 需求澄清、HTML 优先协作、Agent 后台上下文维护 | `review.html`、学习阅读器、质量报告、图示、结构化 change/task 状态 | 希望用户只说目标、Agent 自动维护上下文并持续推进的团队 |
56
63
  | **OpenSpec** | spec / change 生命周期 | Markdown proposal、spec、design、tasks | 更关注 spec 增量治理和变更编排的团队 |
57
64
  | **Superpowers** | skill 驱动的编码执行流 | skills、plans、worktree / subagent 流程、代码评审检查点 | 更关注 AI Agent 如何规划、编码、review、收尾的工程团队 |
58
65
 
59
- OpenPrd 最有特色的地方,在于它把“这次到底在做什么、谁来确认、凭什么继续往下走”
60
- 做成稳定可见的协作面,而不是只留在 spec 文件或 prompt 流程里。
66
+ OpenPrd 最有特色的地方,在于它把“这次到底在做什么、Agent 依据什么继续、最后如何验证”
67
+ 做成稳定可见的协作面,而不是让用户记住 spec 文件、内部口令或 prompt 流程。
61
68
 
62
69
  ## 典型真实场景
63
70
 
@@ -66,7 +73,7 @@ OpenPrd 最有特色的地方,在于它把“这次到底在做什么、谁来
66
73
 
67
74
  | 场景 | 为什么这里更像 OpenPrd 的强项 | 主要产物 |
68
75
  |------|--------------------------------|----------|
69
- | 模糊产品需求,先别急着写代码 | 先澄清,再区分用户确认事实与 Agent 推断,最后把结果沉淀成稳定评审页。 | `clarify`、`capture`、`synthesize`、`review.html` |
76
+ | 模糊产品需求,需要边做边收敛 | 区分用户原始表达、项目事实与 Agent 推断,在推进中持续沉淀稳定评审页。 | `clarify`、`capture`、`synthesize`、`review.html` |
70
77
  | 已有流程或登录入口改造 | 先从仓库与运行态重建当前事实,再决定下一步 change,而不是直接拍脑袋改。 | `discovery`、`diagram`、`review.html`、`change` |
71
78
  | 流程图、界面或架构确认 | 把理解差异放到图示和可评审产物里,而不是埋在聊天记录里。 | `diagram`、`visual-compare`、左右对比 JPG |
72
79
  | 长程 Agent 执行链路 | 把确认后的工作拆成按依赖可执行的小任务,每次新会话只推进一个任务并带验证门禁。 | `tasks`、`loop`、任务提示词、进度日志、验证报告 |
@@ -219,12 +226,12 @@ npx @openprd/cli@latest init /path/to/project --template-pack agent
219
226
 
220
227
  `init` 会创建 `.openprd/`、`docs/basic/`、`AGENTS.md`,并生成 Codex / Claude / Cursor 三端引导。`.openprd/` 是项目内唯一的 OpenPrd 工作区;change、spec、task 和 archive 产物都会收敛到 `.openprd/changes/`、`.openprd/specs/` 和 `.openprd/archive/changes/`,不再在仓库根目录生成单独的 `openprd/` 目录。Codex 项目会同时写入 `.codex/config.toml`、`.codex/hooks.json`、`.codex/hooks/openprd-hook.mjs`,并开启用户级 Codex `hooks = true`。
221
228
 
222
- Codex hooks 默认使用 `lite` 模式:安装 `UserPromptSubmit`、轻量
223
- `PreToolUse` 写入门禁,以及轻量 `Stop` 收工回顾。明确提到 OpenPrd、PRD、深度调研、深度对标、复刻、
229
+ Codex hooks 默认使用 `lite` 模式:安装 `UserPromptSubmit`、非阻断式
230
+ `PreToolUse` 建议,以及轻量 `Stop` 收工回顾。明确提到 OpenPrd、PRD、深度调研、深度对标、复刻、
224
231
  standards、fleet、文档标准化,或看起来像新产品 / 模块 / 流程需求的提示词都会
225
- 注入上下文;`lite` 写入门禁只匹配直接编辑工具,让只读 shell 探查保持安静;`Stop`
232
+ 注入上下文;`PreToolUse` 只向 Agent 提供风险与材料维护建议,不因 OpenPrd 流程材料阻断用户任务;`Stop`
226
233
  会在本轮结束前回顾是否值得沉淀项目经验。
227
- 需要连 shell 命令也进入写入门禁时使用 `guarded`,只有临时深度诊断才使用
234
+ 需要让 shell 命令也获得更完整的风险提示时使用 `guarded`,只有临时深度诊断才使用
228
235
  `full`。
229
236
  如果用户给出报错、日志、复现、根因排查等明确故障证据,并要求直接修复,
230
237
  hook 会按小型 bugfix 处理,不开启需求入口;“确认修复”这类确认词也会关闭
@@ -259,7 +266,7 @@ openprd release /path/to/project
259
266
 
260
267
  如果 OpenPrd 自身要把新版本发布到 GitHub,默认还要推送匹配的版本 tag,并配套 GitHub Release。可以先用 `node scripts/openprd-github-release-notes.mjs /path/to/project --version 0.1.23 --tag v0.1.23 --out /tmp/openprd-release.md` 预览发布文案;仓库内的 `github-release` workflow 会在 tag push 或手动触发时,基于同一份 `release-ledger` 自动创建或更新 GitHub Release。
261
268
 
262
- ### 3. 先向用户澄清
269
+ ### 3. Agent 后台整理需求
263
270
 
264
271
  ```bash
265
272
  openprd clarify /path/to/project
@@ -270,8 +277,8 @@ openprd clarify /path/to/project
270
277
  OpenPrd 会先按用户可见的需求类型接住这句话,而不是先让你填一堆表单:
271
278
 
272
279
  - **直接处理**:通常直接做,做完告诉你改了什么、怎么验。
273
- - **现有功能优化**:先给一版 mini-plan,你确认方向后再继续。
274
- - **新功能 / 新流程方案**:先把场景、范围、第一版和风险说清楚,再进入 `review`、`change` 和 `tasks`。
280
+ - **现有功能优化**:Agent mini-plan 收敛范围并继续执行,显式说明采用的假设。
281
+ - **新功能 / 新流程方案**:Agent 在后台整理场景、范围、第一版和风险,并持续维护 `review`、`change` 和 `tasks`,不要求用户批准这些内部材料。
275
282
 
276
283
  ### 4. 写回答案
277
284
 
@@ -314,18 +321,11 @@ openprd review /path/to/project --open
314
321
  openprd review /path/to/project --mark confirmed --version <id> --digest <sha256> --work-unit <id>
315
322
  ```
316
323
 
317
- `review.html` 是当前 PRD 的稳定评审稿,但默认 approval policy 是
318
- `decision-points`,不是“每次都必须停在这里”。常规 lane 下,一句自然语言
319
- 确认(例如“确认这版,继续”,容忍“确认 v0276 评审稿”这类版本号插写)就足够:
320
- hook 会自动把确认绑定到当前精确的 `--version`、`--digest`、`--work-unit`,
321
- Agent 不允许反过来向用户索要 digest、work-unit 或完整命令。当这句确认同时
322
- 带有“继续执行”意图,或此前已确认过需求摘要时,一次确认会解锁整条链:评审
323
- 记录、change、tasks 与实现全程直通,不再逐环节停下(一次确认合同)。
324
- `silent-record` lane 只有在用户一开始已经明确要求直接做、并显式表示不需要
325
- 额外评审或确认时,才允许直接记录当前这份精确 artifact。不要把实现授权当成
326
- 给任意评审稿补确认,也不要把评审记录当成实现授权。当前 artifact 记录完成后,
327
- 再生成 OpenPrd change 和任务拆解;如果用户原始意图已明确要求实现,tasks
328
- 就绪后即可直接执行,否则等待一句明确的执行指令:
324
+ `review.html` 是当前 PRD 的稳定评审稿,也是用户随时可以查看的协作结果,但不是
325
+ OpenPrd 授权门禁。Agent 自动绑定当前精确的 `--version`、`--digest`、`--work-unit`,
326
+ 自行记录 review、生成 change、拆解 tasks 并继续用户已经要求的工作;不得反过来要求
327
+ 用户粘贴 digestwork-unit、完整命令或批准内部材料。信息不完整时,Agent 优先选择
328
+ 可逆默认方案并说明假设;是否真的需要提问由当前 Agent 根据宿主安全规则与真实上下文判断:
329
329
 
330
330
  ```bash
331
331
  openprd change /path/to/project --generate --change <change-id>
@@ -543,6 +543,8 @@ openprd visual-compare /path/to/project \
543
543
  表格这类重复结构属于默认触发场景,不需要等用户先指出“没有对齐”;只量外框、
544
544
  列宽或行顶不算完整对齐验收。
545
545
 
546
+ 网格、基线和对齐辅助线只用于这条布局校验路径。普通 `before/after`、`reference/actual` 与 `verification-board` 不会自动叠加网格;它们默认使用紧凑的暖色结果画布,让截图和结论占据主要空间。
547
+
546
548
  如果要判断单个 logo、icon、avatar、badge、按钮图形或图片裁切内部是否居中,
547
549
  或者用户反馈“偏心”“视觉重心不对”,Agent 应先裁出目标元素,再生成内部居中证据板:
548
550
 
@@ -685,7 +687,7 @@ openprd loop /path/to/project --run --agent codex --dry-run
685
687
  `--dry-run`,预演时只打印安装和刷新命令,不修改 CLI、项目、registry 或 harness 状态。
686
688
 
687
689
  这套 harness 是有状态的,但 hook 重量由 profile 控制。默认 `lite` 保留轻量
688
- PreToolUse 写入门禁,并把匹配范围限制在直接编辑工具上,同时在 `Stop` 做一轮轻量项目经验回顾,避免只读 shell 噪声和完整工具级遥测;`guarded` 会额外覆盖 shell 工具,`full` 只建议用于临时深度诊断。`freeze`、`handoff`、accepted spec apply/archive、commit、push、release、publish 等高风险动作会先经过 `openprd run . --verify`,覆盖标准化、工作区校验、激活 change 校验和激活 discovery 校验。
690
+ PreToolUse 非阻断式建议,并把匹配范围限制在直接编辑工具上,同时在 `Stop` 做一轮轻量项目经验回顾,避免只读 shell 噪声和完整工具级遥测;`guarded` 会额外覆盖 shell 工具,`full` 只建议用于临时深度诊断。`freeze`、`handoff`、accepted spec apply/archive、commit、push、release、publish 等动作会运行 `openprd run . --verify`,帮助 Agent 检查标准化、工作区、激活 change discovery 状态,但不要求用户补流程确认。
689
691
 
690
692
  `openprd run . --context` 是类似 Ralph 的循环控制面。它会从激活 change 任务、discovery coverage 或普通 OpenPrd 工作流状态里选择下一项可执行单元,并把 hook turn 记录到 `.openprd/harness/iterations.jsonl`。
691
693
 
package/README_EN.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [简体中文](./README.md) | English
4
4
 
5
- > An AI-native PRD workspace and CLI that helps teams clarify requests, confirm direction, and ship with evidence.
5
+ > An AI-native PRD workspace and CLI that helps teams and agents clarify requests, keep moving, and ship with evidence.
6
6
 
7
7
  [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
8
8
  [![Node.js](https://img.shields.io/badge/node-%3E%3D20.19.0-339933.svg)](https://nodejs.org/)
@@ -11,11 +11,18 @@
11
11
  OpenPrd is a lightweight **PRD harness**. Start by describing the problem in plain language, and it helps teams and agents turn that request into:
12
12
 
13
13
  - requirement clarification
14
- - shared confirmation
14
+ - agent-maintained requirement facts and decisions
15
15
  - visual review
16
16
  - structured handoff into execution
17
17
 
18
- Instead of hiding key decisions in prompts or terminal logs, OpenPrd keeps people and agents aligned around stable HTML artifacts such as `review.html`, learning readers, and quality reports.
18
+ Instead of hiding key decisions in prompts or terminal logs, OpenPrd keeps people and agents aligned around stable HTML artifacts such as `review.html`, learning readers, and quality reports. OpenPrd helps the agent do the work: PRDs, reviews, changes, tasks, design contracts, and evidence are maintained in the background without requiring the user to reply with a prescribed confirmation.
19
+
20
+ ## 0.1.22: workflow artifacts are no longer user gates
21
+
22
+ - Missing requirement summaries, review artifacts, design contracts, test evidence, or risk classifications no longer block implementation.
23
+ - Production, payment, deletion, account-switching, fallback, and hardcoding signals provide safety guidance to the agent; OpenPrd does not request user approval.
24
+ - Skill/AGENTS diagrams and large-UI design candidates explain decisions without becoming write or implementation gates.
25
+ - Codex, Claude Code, and Cursor share the same agent-maintained, user-task-first behavior.
19
26
 
20
27
  ![OpenPrd capability overview](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-capability-overview-en.png)
21
28
 
@@ -25,14 +32,14 @@ OpenPrd is designed for the gap between:
25
32
 
26
33
  - vague product ideas that need clarification
27
34
  - agent-assisted requirement drafting
28
- - human confirmation at the right decision points before implementation
35
+ - durable decisions and evidence without forcing process stops before implementation
29
36
  - structured handoff into execution systems
30
37
 
31
38
  It is especially useful when you want:
32
39
 
33
40
  - **clarify before drafting** instead of jumping straight to implementation
34
41
  - **source-aware capture** so user-confirmed facts stay separate from repo-derived, agent-inferred, or agent-normalized context
35
- - **policy-based review gates** that keep stable artifacts without forcing the same stop every time
42
+ - **non-blocking review artifacts** that preserve context without turning process material into user approval gates
36
43
  - **agent-facing skills** shipped with the tool, not hidden in a local environment
37
44
 
38
45
  If your teammates often say “we kind of know what we want, but it is not fully shaped yet”, that is usually the moment when OpenPrd is most useful.
@@ -261,13 +268,13 @@ npx @openprd/cli@latest init /path/to/project --template-pack agent
261
268
 
262
269
  `init` creates `.openprd/`, `docs/basic/`, `AGENTS.md`, and generated Codex / Claude / Cursor guidance. Codex projects also get `.codex/config.toml`, `.codex/hooks.json`, `.codex/hooks/openprd-hook.mjs`, and user-level Codex `hooks = true`.
263
270
 
264
- Codex hooks default to `lite`: `UserPromptSubmit`, a lightweight `PreToolUse`
265
- write gate, and a lightweight `Stop` end-of-turn review. Context is injected for prompts that explicitly mention OpenPrd,
271
+ Codex hooks default to `lite`: `UserPromptSubmit`, non-blocking `PreToolUse`
272
+ guidance, and a lightweight `Stop` end-of-turn review. Context is injected for prompts that explicitly mention OpenPrd,
266
273
  PRD, deep research/benchmarking, replication, standards, fleet, documentation
267
274
  standards, or look like new product/module/workflow requirements. The lite write
268
- gate only matches direct editing tools so read-only shell exploration stays
269
- quiet, while `Stop` reviews whether the current turn produced a reusable project
270
- pattern; use `guarded` when shell commands should also pass through the write gate,
275
+ guidance helps the agent maintain context and choose safer paths without blocking
276
+ the requested task, while `Stop` reviews whether the current turn produced a reusable project
277
+ pattern; use `guarded` when shell commands should also receive fuller risk guidance,
271
278
  and `full` only for temporary deep diagnostics.
272
279
  Concrete bugfix prompts with diagnostic evidence such as errors, logs, repro
273
280
  steps, or root-cause investigation skip requirement intake when the user asks to
@@ -308,7 +315,7 @@ openprd release /path/to/project
308
315
 
309
316
  When OpenPrd itself publishes a new version to GitHub, the release should also include a matching version tag and GitHub Release. You can preview the body with `node scripts/openprd-github-release-notes.mjs /path/to/project --version 0.1.23 --tag v0.1.23 --out /tmp/openprd-release.md`; the repo `github-release` workflow will create or update the GitHub Release from the same `release-ledger` on tag push or manual dispatch.
310
317
 
311
- ### 3. Clarify with the user
318
+ ### 3. Maintain requirement context in the background
312
319
 
313
320
  ```bash
314
321
  openprd clarify /path/to/project
@@ -319,8 +326,8 @@ Clarification stays in the conversation as an inline outline or short checklist.
319
326
  OpenPrd first routes the request by user-visible need type instead of forcing a long intake form:
320
327
 
321
328
  - **Quick fix**: usually handle it directly, then report what changed and how it was verified.
322
- - **Existing-flow improvement**: first share a mini-plan in plain language, then continue after direction is confirmed.
323
- - **New feature / new workflow**: first clarify the scenario, scope, first version, and risks, then move into `review`, `change`, and `tasks`.
329
+ - **Existing-flow improvement**: maintain a plain-language mini-plan, state assumptions, and keep moving.
330
+ - **New feature / new workflow**: maintain the scenario, scope, first version, risks, `review`, `change`, and `tasks` in the background without asking the user to approve those internal artifacts.
324
331
 
325
332
  ### 4. Capture answers back into the workspace
326
333
 
@@ -363,25 +370,13 @@ openprd review /path/to/project --open
363
370
  openprd review /path/to/project --mark confirmed --version <id> --digest <sha256> --work-unit <id>
364
371
  ```
365
372
 
366
- `review.html` is the stable review artifact for the current PRD, but the default
367
- approval policy is `decision-points`, not “always stop here”. In a normal lane,
368
- one plain natural-language confirmation (for example “确认这版,继续”, including
369
- wording with an inline version id such as “确认 v0276 评审稿”) is enough: the
370
- hook binds it to the exact current `--version`, `--digest`, and `--work-unit`
371
- tuple automatically, and the agent must never ask the user to paste a digest,
372
- work-unit id, or a full command. When that confirmation also carries a
373
- continue-execution intent, or a requirement summary was already confirmed
374
- earlier, one confirmation authorizes the whole chain: review recording, change,
375
- tasks, and implementation proceed without further stops (the one-time
376
- confirmation contract). In a `silent-record` lane, OpenPrd can record the exact
377
- current artifact without an extra stop only when the user already made direct
378
- execution intent explicit and explicitly opted out of additional review
379
- confirmation. Do not treat implementation approval as permission to mark a
380
- different review artifact, and do not treat review recording as execution
381
- authorization. After the current artifact is recorded, generate the OpenPrd
382
- change and task breakdown. If the user originally asked to implement, execution
383
- can continue once tasks are ready; otherwise wait for an explicit execution
384
- request:
373
+ `review.html` is a stable collaboration artifact, not an OpenPrd authorization
374
+ gate. The agent binds the exact current `--version`, `--digest`, and `--work-unit`,
375
+ records the review, generates the change and tasks, and continues the work the
376
+ user requested. It must not ask the user to paste a digest, work-unit id, command,
377
+ or approval for internal process material. When information is incomplete, the
378
+ agent should choose a reversible default and state the assumption; whether a real
379
+ question is necessary is decided by the active agent and host safety rules:
385
380
 
386
381
  ```bash
387
382
  openprd change /path/to/project --generate --change <change-id>
@@ -626,6 +621,8 @@ prices, buttons, icons, and action areas. Repeated card lists, card grids, and
626
621
  tables are default triggers even when the user did not explicitly complain
627
622
  about alignment; measuring only outer frames, columns, or row tops is not enough.
628
623
 
624
+ Grid, baseline, and alignment overlays are exclusive to this layout-validation path. Regular `before/after`, `reference/actual`, and `verification-board` outputs do not add grids automatically; they use a compact warm result canvas that keeps screenshots and verdicts prominent.
625
+
629
626
  When a single logo, icon, avatar, badge, button graphic, or image crop needs
630
627
  internal centering review, or when the user reports that its visual weight feels
631
628
  off-center, crop the target if needed and generate a centering evidence board:
@@ -795,15 +792,15 @@ or, with `--fleet`, `fleet <root> --update-openprd`. Both commands support
795
792
  modifying the CLI, project, registry, or harness state.
796
793
 
797
794
  The harness is stateful, but hooks are proportional to the chosen profile.
798
- Default `lite` keeps a lightweight `PreToolUse` write gate for requirement
799
- intake and limits it to direct editing tools, while `Stop` performs a lightweight
795
+ Default `lite` keeps lightweight, non-blocking `PreToolUse` guidance for requirement
796
+ context and limits it to direct editing tools, while `Stop` performs a lightweight
800
797
  end-of-turn knowledge review instead of full telemetry. This avoids read-only shell hook
801
- noise while still nudging the agent to capture reusable project patterns. `guarded` also gates shell tools, while
798
+ noise while still nudging the agent to capture reusable project patterns. `guarded` also covers shell tools, while
802
799
  `full` restores SessionStart/PreToolUse/PostToolUse/Stop telemetry for temporary
803
- diagnostics. High-risk actions such as freeze, handoff, accepted spec
804
- apply/archive, commit, push, release, or publish are gated by
805
- `openprd run . --verify`, which covers standards, workspace validation, active
806
- change validation, and active discovery verification.
800
+ diagnostics. Actions such as freeze, handoff, accepted spec apply/archive,
801
+ commit, push, release, or publish run `openprd run . --verify` to help the agent
802
+ check standards, workspace validation, active change validation, and active
803
+ discovery verification without requesting process confirmation from the user.
807
804
 
808
805
  `openprd run . --context` is the Ralph-style loop surface for agents. It selects
809
806
  the next executable unit from active change tasks, discovery coverage, or normal
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openprd/cli",
3
- "version": "0.1.19",
3
+ "version": "0.1.22",
4
4
  "description": "AI-native PRD workspace and lifecycle CLI",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -135,6 +135,21 @@ description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任
135
135
  - 每个方向都要写清:为什么它和另外两版不同、适合什么场景、主要风险是什么。
136
136
  - 每个方向还要写清:审美主张是什么、用户会记住什么、它避免了哪种通用 AI 模板味。
137
137
 
138
+ ### 5a. 界面效果图生成质量合同
139
+
140
+ - Agent 不需要等待用户补一句“请生图”。当语义判断属于大界面改动且视觉决策成本高时,默认主动生成 3 个可评审方向,并在实现前停下来让用户选择。
141
+ - 每次生成前都要写清用途、目标用户、产品气质、业务约束、核心动作和唯一记忆点;效果图必须服务于任务路径,不能只追求展示感。
142
+ - 视觉质量从字体角色、色彩系统、空间构图、信息层级、表面语言、图标语言、动效含义和氛围细节一起判断。复杂度要与审美主张匹配,工具界面优先扫描效率和状态清晰,叙事界面才允许更强的视觉张力。
143
+ - 避免通用 AI 模板味:无依据的蓝紫渐变、默认字体、等权白卡堆叠、过量大圆角、无语境装饰、只换颜色的伪方向,以及为了“高级”牺牲可读性。
144
+ - 3 个方向必须改变真正的设计决策,例如信息架构、首屏重心、任务路径、内容密度或空间组织;不能只改变颜色、插图或装饰。
145
+
146
+ ### 5b. 既有界面的视觉 DNA 继承
147
+
148
+ - 只要已有产品截图、设计稿或可运行界面,默认进入 `preserve-existing`,而不是自由改风格。除非用户明确要求换风格,否则锁定现有字体角色、色彩系统、明暗模式、表面语言、圆角/边框/阴影体系、图标语言、平台框架和信息密度。
149
+ - 既有界面的 3 个方向用同一张当前界面截图做 image-to-image 参考,每次生图都必须携带该参考图;探索范围主要放在布局、信息层级、导航、关键路径和空间构图,不得把品牌视觉重做成三个陌生产品。
150
+ - 用户明确要求参考另一种风格、品牌升级或整体重设计时,才把对应锁定项解开,并记录在 `direction-plan.md` 与 `selected-direction.md`。
151
+ - 冷启动新功能没有现有界面时,不伪造“修改前截图”;改用已确认 PRD、用户、首版范围、业务约束和视觉目标形成设计 brief,再生成异质方向。
152
+
138
153
  ### 6. Theme Lock Before Build
139
154
 
140
155
  - 一旦方向已选,先锁定 `lens + theme + layout + component set + aesthetic direction + memory point`,再进入编码。
@@ -176,6 +191,7 @@ description: 为 OpenPrd 的界面、页面、视觉、样式和前端体验任
176
191
  - 视觉证据不仅看像不像,还要看选定的气质、记忆点、字体/色彩/动效/表面层级有没有被实现保住。
177
192
  - 卡片宽度、间距、留白、对齐、颜色、圆角、字号、按钮和图标这类轻量 UI 可视优化,不需要自动升级成 3 方向方案评审;但只要最终会被用户看见,收口时就要有 `visual-compare` 的修改前后图、局部焦点证据板、截图实测证据板或对齐辅助线证据板。构建通过、打包成功、`dev-check` 通过和单张截图都不能替代视觉证据。
178
193
  - 新功能或改动里只要出现同构列表、卡片、网格或表格,就默认把容器轨道以及相同文案类型/相同组件槽位的对齐纳入验收;Agent 应截真实页面、叠辅助线,同时量卡片外框、列宽、行顶等容器轨道,以及标题、副标题、描述、标签、状态、价格、按钮、图标、操作区等内部内容槽位的 x/y/宽高/baseline spread,并用 `openprd visual-compare . --board <alignment-board.json>` 生成对齐证据。只量外框、列宽或行顶不算完整对齐验收。
194
+ - 网格、基线和对齐辅助线属于布局校验材料,只在布局、间距、对齐、同构列表、卡片、网格或表格命中 `alignment-board` 时生成。普通截图、最终 before/after、reference/actual 和 verification-board 只负责展示结果,不默认叠加网格或基线。
179
195
  - 单个 logo、icon、avatar、badge、按钮图形或图片裁切需要判断内部居中、视觉重心或偏心时,默认使用 `openprd visual-compare . --board <centering-board.json>` 生成内部居中证据板;Agent 要先裁出目标元素,再用类似 Canvas 的像素 mask 量画布中心、主体外接框中心和视觉重心偏移。证据板必须显示红色画布中心线、绿色主体外接框、黄色视觉重心点和 offset 数值;单张截图或主观“看起来居中”不算完整验收。
180
196
 
181
197
  ## 输出要求
@@ -54,8 +54,8 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
54
54
  20. 用户要求日志、链路追踪、业务成本护栏、免费额度、滥用防护、评估执行环境、冒烟覆盖、性能基线、极端场景、HTML 质量评估报告或项目级经验 Skill 时,路由到 `$openprd-quality`
55
55
  21. 用户需要可视化说明,或系统/产品形态仍不清晰时,在进入需求定稿前路由到 `$openprd-diagram-review`
56
56
  22. 默认保持 Codex hooks 轻量。除非项目明确需要完整工具级遥测,否则 `openprd setup/update` 使用 `--hook-profile lite`;默认 `lite` 会保留 `Stop` 收工回顾,用于在本轮结束前提醒是否值得沉淀项目经验,并要求 Agent 用“本次情况 / 准备整理成的经验 / 以后如何复用 / 只保留在当前项目里”的结构化人话向用户确认
57
- 23. hook 会强制阻断几类场景:需求入口未完成就写实现、外部证据不足就直接改第三方集成、skill/AGENTS 变更未先可视化确认、敏感信息场景下直接读原始 vault 文件,以及未经当前用户明确批准的云端热修复、生产远端写入、业务兜底、写死逻辑或缓存补行
58
- 24. 即使用户已经授权实现,也不自动授权云端热修复、生产远端写入、客户端/服务端补业务数据、接口临时插入业务行、缓存补行、硬编码或写死逻辑。发现这类路径时先停下,说明为什么标准源码/迁移/配置路径不够、影响范围、回滚方式、本地同步计划和验证方式;只有用户明确说允许热修复、允许临时兜底或允许写死后才执行。
57
+ 23. hook 默认不因 PRD、review、change、tasks、设计合同、测试报告或视觉证据尚未补齐而阻断用户要求的正常实现。缺失材料由 Agent 在后台自动补齐;来不及补齐时继续完成安全范围内的工作,并在收口如实说明证据状态,不把流程作业转嫁给用户。
58
+ 24. 风险识别只向 Agent 提供提醒和更安全的实现建议,不承担授权审批。命中“兜底、写死、补数据、权益、额度、生产、支付、删除、账号”等词时先看真实动作对象,优先改成配置、迁移、标准状态机、幂等脚本或可回滚发布路径并继续。OpenPrd 不因风险词或动作类型阻断工具调用,也不向用户索取确认、指定句子、摘要、digest、work-unit id 或命令;是否需要确认由当前 Agent 依据宿主安全规则和真实上下文自行判断。
59
59
  25. 当 `doctor` 报告生成引导漂移时,读取 `.openprd/harness/drift-report.json`
60
60
  26. `openprd run . --context` 会返回 `runtimeEnvironment`。先按 `.openprd/harness/runtime-environment.json` 和 install manifest 的 `platformCapabilityPacks` 判断当前对话是在 Codex、Claude Code 还是 Cursor,再启用对应能力;Codex Image 2、Computer Use、Codex-owned browser window、对话协同画布和当前线程文本桥接都必须有当前 surface 或 hook/session 证据,不能只凭 Codex CLI 或配置文件存在来启用。当前线程桥接只在 Codex App 明确提供线程发送工具时使用;画布图片仍以导出路径或 Markdown 图片引用作为证据,不宣称网页能自动直发附件。
61
61
 
@@ -83,7 +83,7 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
83
83
  - 不要把 `run --context` 建议当作直接用户命令
84
84
  - 用户给出会话 ID 续接历史任务时,使用 `openprd run <path> --context --message <用户原话或会话ID>` 保留通用会话 ID 语义;先恢复指定会话,不要让当前 active change 抢主线
85
85
  - 用户没有给 ID、但明确描述了已有需求/任务对象时,也使用 `openprd run <path> --context --message <用户原话>`;先解析对应的 change/task/work unit,再决定是否沿用当前工作区状态
86
- - 默认 lite Codex hooks 会为明确的 OpenPrd、PRD、深度调研、对标复刻、standards、fleet、文档标准化提示词,以及结构上较复杂的需求注入 `$openprd-requirement-intake` 分流提示;直接处理(L0)不打开 requirement gate,现有功能优化(L1)用对话内 mini-plan 承接,新功能/新流程方案(L2)才进入 PRD/review/change/tasks;轻量 `PreToolUse` 写入门禁会在需求入口未确认前阻断过早实现;本轮准备结束时,`Stop` 会基于 touched files 和 verify/finish 信号回顾是否要生成项目经验草案,并要求 Agent 先用人话向用户确认是否保留到当前项目里
86
+ - 默认 lite Codex hooks 会为明确的 OpenPrd、PRD、深度调研、对标复刻、standards、fleet、文档标准化提示词,以及结构上较复杂的需求注入 `$openprd-requirement-intake` 分流提示;直接处理(L0)不打开 requirement 维护,现有功能优化(L1)用对话内 mini-plan 承接,新功能/新流程方案(L2)在后台维护 PRD/review/change/tasks;`PreToolUse` 不因这些材料缺失阻断实现;`Stop` 只提醒 Agent 评估是否值得生成项目经验草案,不强制用户确认
87
87
  - 只有当项目确实需要完整 hook 遥测或临时深度诊断时,才用 `openprd update <path> --hook-profile full`
88
88
  - 长程实现循环使用:
89
89
  - `openprd loop <path> --init`
@@ -99,7 +99,7 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
99
99
  - 只有在当前用户消息明确要求开发、继续任务、深度调研、对标复刻或提交时,才运行 `openprd loop <path> --run`
100
100
  - 代码修改完成后、最终回复前,运行 `openprd dev-check <path> <file...>`;自动优化开启(默认)时需要关注的文件先本轮完成拆分,再以 **OpenPRD 自动优化报告** 表格呈现(列:影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议)并附开关确认;关闭后以 **后续建议** 表格呈现(列:影响对象、关注程度、规模信号、预警原因、本次处理结果、后续建议)。两种模式都按 🔴 → 🟠 → 🟡 排序
101
101
  - 用户只是要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup 或先看样子时,默认调用 `imagegen`(Codex 原生 Image 2)生成图片;Image 2 是工具路径,不是审美豁免,生成前先写清用途、受众、气质、约束和记忆点;除非用户明确指定 HTML/SVG/CSS/Canvas/代码稿,不要生成临时 HTML 再截图;未调用 `imagegen` 前,不要声称生图已完成、失败或限流。生图结果先当候选效果图,不要默认纳入验收
102
- - 大界面改动不直接开工:先按用户目标、信息架构变化、视觉决策成本和验证风险判断方案评审形态;已有界面时用 Codex Computer Use 打开产品内对应功能并截图,冷启动没有现有界面时用已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成设计 brief;再用 `imagegen`(Codex 原生 Image 2)生成至少 3 个设计方向,横向拼接成一张带 1/2/3 序号的大图作为候选效果图给用户确认;每个方向都要有具体审美主张和 anti-slop 自检;主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现;只有确认后,再把它作为实现参考图进入后续任务
102
+ - 大界面改动先按用户目标、信息架构变化、视觉决策成本和验证风险判断方案评审形态;已有界面时用 Codex Computer Use 打开产品内对应功能并截图,冷启动没有现有界面时用当前 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成 design brief;再用 `imagegen`(Codex 原生 Image 2)生成至少 3 个设计方向,横向拼接成一张带 1/2/3 序号的大图作为候选效果图;每个方向都要有具体审美主张和 anti-slop 自检。候选图用于帮助用户判断,但 OpenPrd 不强制停下等待确认;Agent 可按最符合目标且可逆的方向继续,并清楚说明采用的假设
103
103
  - 如果已有确认参考效果图、图片资产、设计稿、截图或用户给图并进入实现阶段,阶段性完成后必须生成实现截图,并用 `openprd visual-compare <path> --reference <效果图> --actual <实现截图> --locale <zh-CN|en>` 输出 JPG 视觉对比图;如果参考图里有多个子图、网格或对象,先运行 `openprd visual-prepare <path> --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`,检查 contact sheet 后按 compare-plan 逐项对比;如果局部细节更重要,再补 `--board <focus-board.json>` 输出局部焦点证据板;如果没有明确参考图,先判断新建界面还是修改既有界面:新建界面先完成 3 方向方案评审,修改既有界面动手前先生成修改前截图,完成后生成修改后截图,并用 `openprd visual-compare <path> --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>` 输出 JPG 自检图;如果并行试了多个优化方向,再补 `--board <parallel-board.json>` 输出并行实验证据板;如果新功能或改动包含同构列表、卡片、网格、表格,或用户反馈没对齐/排版漂移,再补 `--board <alignment-board.json>` 输出对齐辅助线证据板。未查看对比图,或对比图仍有明显结构、气质、层级、字体/色彩/表面角色、记忆点差异/漂移时,不要声称界面视觉完成;如果用户后续说“跟效果图”“不一致”“好丑”“复刻”,至少先产出一份视觉证据图
104
104
  - `openprd loop <path> --finish` 前,先完成文档影响检查并更新缺失或过期的 `docs/basic/`、文件说明书和文件夹 README;涉及后端、脚本、Agent、工具链、服务或数据处理变更时,同步评估 CLI 与 API 两个接入面
105
105
  - 声称单个任务完成前,只运行本任务最小足够验证,并通过 `--evidence`、测试报告或任务 metadata 留下 task-scoped evidence;不要在每个任务里反复运行 `openprd quality <path> --verify` 或全局 `openprd run <path> --verify`
@@ -121,7 +121,7 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
121
121
  - 使用:
122
122
  - `openprd clarify <path>`
123
123
  - 当关键产品事实缺失时,先查看 `intake-reflection.md` 的需求入口自省,再把压缩后的必须确认问题问给用户
124
- - 当需求模糊、起点只有一句想法,或需要先做方案探索时,先查看生成的 `intake-reflection.md`,先把用户群体、产品形态、第一版切片、暂不处理、不能破坏和风险探针整理成首轮项目画像,再把压缩后的目标、范围、非目标、验收方式和必须确认问题放在对话里请用户确认;不要生成或打开澄清 HTML
124
+ - 当需求模糊、起点只有一句想法,或需要先做方案探索时,先查看生成的 `intake-reflection.md`,把用户群体、产品形态、第一版切片、暂不处理、不能破坏和风险探针整理成首轮项目画像;Agent 选择最可逆的默认方案继续,把假设和验收方式说清楚,不把 OpenPrd 摘要变成用户确认门禁;不要生成或打开澄清 HTML
125
125
  - Agent 在对话里先用业务和产品语言复述:这次主要给谁、什么场景、先解决什么、先不碰什么、不能影响什么、会带来哪些业务风险。默认先追问 1 个最高价值问题,而不是一次性抛一整墙技术问题。
126
126
  - `需求判断` 和 `需求理解` 先用 1 到 2 句轻量主句说清结论:这次是什么、核心问题在哪里、第一版先做到什么;边界、风险、异常例子和技术细节下沉到后续分项或表格,不要揉成一大段重话。
127
127
  - 如果当前还是 L2 的首轮澄清或 requirement 摘要确认阶段,只能承诺“我先整理需求摘要给你确认,确认后再进入 PRD / review 流程”;不要写成“你回我一句我就开始实现”,也不要把 requirement 摘要确认、review 和实现压成一步。
@@ -152,10 +152,10 @@ description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。
152
152
  - 生成 `spec.md` 和 tasks 时跟随用户当前主语言;无法判断时用简体中文兜底。必要专有名词、品牌名、命令名、路径、字段名和 API 术语可以保留原文
153
153
  - `synthesize` 生成 `review.html` 后,必须把 HTML 路径告诉用户,并自动打开它(或紧接着运行 `openprd review <path> --open`)
154
154
  - 评审页里的需求关系图、需求流程图和重点摘要不要靠 HTML 截断;`openprd synthesize` 生成版本快照后,不要直接把 review 给用户确认。必须先用 `openprd review-presentation <path> --template` 查看展示文案契约,让 Agent 按 `reviewPresentation` 写短文案,再用 `openprd review-presentation <path> --presentation <json> --write --fail-on-violation` 校验并写回。脚本通过后会写入校验元信息并重渲染可确认 review.html;超限时按脚本返回的 jsonPath 和字数限制重新提炼,不手工改快照、不裁剪原文
155
- - L1/L2 需求涉及界面、页面或交互时,review-presentation 写入前先补交互方向评审:用 `imagegen`(Codex 原生 Image 2)生成 3 个差异足够大的交互稿方向,图片保存到 `.openprd/design/active/`,再把每个方向的 `id/title/image/summary/tradeoff` 写入 `reviewPresentation.designDirections.directions[]`(title 15 字内、summary/tradeoff 30 字内)。review.html 会渲染 3 方向评审卡片,用户点“选这个方向”后回传 `openprd review <path> --mark confirmed --direction <id>` 命令;选定方向会记录进评审状态,后续实现必须按选定方向推进。不涉及界面时不要携带 designDirections 字段
155
+ - L1/L2 中只有语义判断为大界面改动、视觉决策成本高或需要用户选方向时,才在 review-presentation 写入前自动补交互方向评审;轻量 UI 微调不触发。按当前工具面用 Codex `imagegen`(Image 2)或 Cursor `GenerateImage` 生成 3 个差异足够大的交互稿方向,图片保存到 `.openprd/design/active/`,再把每个方向的 `id/title/image/summary/tradeoff` 写入 `reviewPresentation.designDirections.directions[]`(title 15 字内、summary/tradeoff 30 字内)。已有界面时三个方向必须共享同一张当前截图作为 image-to-image 参考并默认保持视觉 DNA;冷启动才使用 design brief。review.html 会渲染 3 方向评审卡片,用户点“选这个方向”后回传 `openprd review <path> --mark confirmed --direction <id>` 命令;选定方向会记录进评审状态,后续实现必须按选定方向推进。不涉及界面或只是轻量微调时不要携带 designDirections 字段
156
156
  - 用户想在交互稿上圈选、批注或做视觉级反馈时,引导走画布评审协同:画布右栏顶部“评审协同”区显示当前 7 步流程位置,“导入评审方向”会把当前 review 的 designDirections 连图带说明摆上画布(已选定方向会标出),用户圈选批注后用“发送给 Codex”回传反馈
157
157
  - 用户问“现在到哪一步了”“接下来做什么”“OpenPrd 到底是干嘛的”时,先运行 `openprd guide <path>`:它按工作区状态输出 7 步流程(需求澄清 → 需求摘要 → 评审确认 → 交互方向选择 → 任务拆解 → 实现执行 → 验证收口)、当前位置和下一步动作,用它的输出向用户解释,不要口头即兴复述流程
158
- - 把生成的 `review.html` 当作首选稳定评审 artifact。默认 approval policy `decision-points`:当前 lane 仍需要人类决策时,请用户先评审问题定义、范围、主流程、风险和开放问题,再运行带精确 `--version`、`--digest`、`--work-unit` `openprd review <path> --mark confirmed`。L2 下先确认对话内 requirement 摘要,再写回确认事实、classify/synthesize,并进入这一步 review。若用户一开始已经明确要求直接做,并显式表示“不需要进行任何确认”,lane 才可进入 `silent-record`;单纯的“请帮我实现/继续实现”或“不要评审”都不触发这个豁免。进入 `silent-record` 后也只允许记录当前精确匹配的稳定 artifact,不能借机替别的版本补确认。review 记录完成且 tasks 就绪后,如果用户刚刚确认的是现有功能优化(L1)的 mini-plan、范围边界或正式产品边界,后续承接要写成“已确认,我按这个继续”,不要写成“确认,我们就按这个……”这种像再次索取确认的句子;如果用户原始意图已经明确要求实现,可直接继续执行;否则先输出执行确认清单,列出本轮目标、将执行内容、不做事项、验证方式和已知风险,再请求明确执行授权,不能只要求用户回复一句确认
158
+ - 把生成的 `review.html` 当作稳定评审 artifact,但它是 Agent 后台维护和用户随时可看的结果,不是授权门禁。Agent 用精确 `--version`、`--digest`、`--work-unit` 记录当前稳定 artifact,自行完成 requirement 写回、classify/synthesizereview、change tasks;不得要求用户批准摘要、评审稿或执行清单,也不得因这些材料尚未完成阻断用户已经要求的实现
159
159
  - 在 L2 的 requirement 摘要确认前,不要承诺“确认后我就开始实现”;正确顺序是:先确认摘要,再写回事实、进入 classify/synthesize/review,review 和 tasks 就绪后才谈执行。
160
160
 
161
161
  ### 6. 需要时生成可视化评审产物
@@ -34,7 +34,7 @@ description: 评估 OpenPrd 的可观测性、业务成本与滥用护栏、评
34
34
  - `openprd visual-compare <path> --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>`
35
35
  - `openprd visual-compare <path> --board <focus-board.json|parallel-board.json|verification-board.json|alignment-board.json> --locale <zh-CN|en>`
36
36
  - 大界面改动的实现前方案评审:
37
- - 先按用户目标、信息架构变化、视觉决策成本和验证风险判断方案评审形态;已有界面时用 Codex Computer Use 截取产品内当前功能截图,冷启动没有现有界面时用已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成设计 brief;再用 `imagegen`(Codex 原生 Image 2)生成至少 3 个设计方向,并保存横向拼接评审大图到 `.openprd/harness/visual-reviews/`
37
+ - 先按用户目标、信息架构变化、视觉决策成本和验证风险判断方案评审形态,用户无需另行提出生图;已有界面时按平台能力截取当前真实界面,三个方向共享同一截图并默认保持原视觉 DNA;冷启动用已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成 design brief;再按工具面用 Codex `imagegen`(Image 2)或 Cursor `GenerateImage` 生成至少 3 个设计方向,并保存横向拼接评审大图到 `.openprd/harness/visual-reviews/`
38
38
  - 基于已审查报告生成或刷新项目级经验:
39
39
  - `openprd quality <path> --learn --from <candidate-dir|report-id-or-json>`
40
40
  - 审查执行中发现的配置、规则候选或 user-local 偏好:
@@ -42,7 +42,7 @@ description: OpenPrd 需求入口与 PRD 分流 skill。用于用户提出产品
42
42
  用户审查时优先把路由码并进“需求类型:直接处理(L0)”这类标签里,不要把内部调度码单独抬成标题。只有审查或调试真的受益时,才额外补“内部路由码:L1”这类信息,并保留上面的对照关系。
43
43
  用户侧表达优先使用“面向个人消费者场景 / 面向企业服务场景 / 以 Agent 为主要使用场景”这类自然语言,不要把 `consumer`、`b2b`、`agent` 直接当展示词抛给用户。
44
44
 
45
- 界面、页面、视觉、样式或前端体验需求需要额外判断 UI 影响面。若会明显改变信息架构、核心布局、主视觉、关键路径、组件层级/密度,或用户需要先选择设计方向,即使属于“现有功能优化”,也要先走“大界面改动视觉方案评审”:已有界面时用 Computer Use 截取当前产品内功能截图,冷启动没有现有界面时基于已确认 PRD、用户群体、第一版切片和视觉目标生成设计 brief;再用 `imagegen`(Codex 原生 Image 2)生成至少 3 个方向,横向拼接带 1/2/3 序号的大图给用户确认。
45
+ 界面、页面、视觉、样式或前端体验需求需要额外判断 UI 影响面。若会明显改变信息架构、核心布局、主视觉、关键路径、组件层级/密度,或用户需要先选择设计方向,即使属于“现有功能优化”,也要自动走“大界面改动视觉方案评审”,不要求用户另行提出生图:已有界面时,在 Codex 原生 App 用 Computer Use、Codex 网页环境用 Chrome 插件的任务专用窗口、Cursor 用当前可用的浏览器或项目预览能力截取真实界面;同一截图作为每个方向的 image-to-image 参考,除非用户明确要求换风格,否则保持现有视觉 DNA。冷启动没有现有界面时基于已确认 PRD、用户群体、第一版切片和视觉目标生成 design brief。随后按当前工具面选择 Codex `imagegen`(Image 2)或 Cursor `GenerateImage` 生成至少 3 个方向,横向拼接带 1/2/3 序号的大图给用户确认。卡片宽度、间距、对齐、颜色、圆角、字号等轻量微调不自动升级为三方向评审。
46
46
 
47
47
  如果同一句话同时包含“继续旧任务”和“新增范围”,先判断新增范围是否超出旧 PRD。超出时必须回到需求入口,更新 PRD/change/tasks,不能把“继续”当作实现授权。
48
48