@openprd/cli 0.1.0

package/skills/openprd-diagram-review/examples/architecture-zh.md

@@ -0,0 +1,8 @@
+用户请求：
+请在需求澄清后，帮我画一张这个 AI 教学产品的架构图，并让我确认边界、依赖和 review 流程。
+
+期望行为：
+- 选择 architecture 视图
+- 跟随中文输出
+- 保留 OpenPrd / OpenSpec / PostgreSQL 等专有名词
+- 生成图后要求用户确认缺失系统、错误边界和未决问题

package/skills/openprd-diagram-review/examples/product-flow-zh.md

@@ -0,0 +1,7 @@
+用户请求：
+把新用户首次完成一个教学任务的流程图画出来，包含失败路径和需要确认的节点。
+
+期望行为：
+- 选择 product-flow 视图
+- 如果当前 CLI 只有 architecture renderer，也不要假装有 flow renderer
+- 先生成 flow contract，再引导用户确认步骤、分支和异常路径

package/skills/openprd-diagram-review/references/cocoon-patterns.md

@@ -0,0 +1,17 @@
+# Patterns Borrowed from Cocoon AI Architecture Diagram Generator
+
+Borrow these ideas:
+
+- self-contained HTML artifact
+- inline SVG
+- stable visual grammar
+- summary cards below the diagram
+- explicit review instructions
+- metadata/footer line
+- legend with semantic categories
+
+Do not copy rigidly:
+
+- do not hardcode English labels
+- do not overload one contract for all diagram types
+- do not assume only architecture views matter; product-flow review is often equally important for OpenPrd

package/skills/openprd-diagram-review/references/diagram-contracts.md

@@ -0,0 +1,126 @@
+# Diagram Contracts
+
+## Language Requirement
+
+For `locale: zh-CN`, all visible user-facing text in the contract must be Simplified Chinese. This includes `title`, `subtitle`, component names/subtitles/details, flow labels, summary cards, side panels, and review instructions.
+
+Preserve necessary proper nouns and technical tokens inside Chinese sentences, such as MotiClaw, Electron, TypeScript, CLI, API, JSON, NDJSON, dry-run, Host API, schema, and `waiting_approval`. Do not write full English sentences just because the diagram contains technical terms.
+
+## Architecture Diagram Contract
+
+### Minimum required fields
+
+- `type` = `architecture`
+- `title`
+- `components[]`
+- `flows[]`
+- `summaryCards[]`
+- `reviewInstructions[]`
+- `metadata.versionId`
+- `metadata.reviewStatus`
+
+### Fields the agent MUST fill
+
+- `title`
+- each component: `id`, `name`, `type`
+- each flow: `source`, `target`, `label`
+- at least one summary card
+- at least one review instruction
+- `metadata.versionId`
+- `metadata.reviewStatus`
+
+### Fields that may fallback
+
+- `locale`
+- `subtitle`
+- component `subtitle`
+- component `details`
+- `sidePanels`
+- `metadata.owner`
+- `metadata.targetSystem`
+
+Use fields such as:
+
+- `locale`
+- `title`
+- `subtitle`
+- `scope.inScope`
+- `scope.outOfScope`
+- `components[]`
+  - `id`
+  - `name`
+  - `type`
+  - `subtitle`
+  - `details[]`
+- `boundaries[]`
+- `flows[]`
+- `summaryCards[]`
+- `assumptions[]`
+- `reviewInstructions[]`
+- `metadata`
+  - `reviewStatus` (`pending-confirmation` | `confirmed` | `needs-revision`)
+
+## Product-Flow Diagram Contract
+
+### Minimum required fields
+
+- `type` = `product-flow`
+- `title`
+- `actors[]`
+- `steps[]`
+- `transitions[]`
+- `summaryCards[]`
+- `reviewInstructions[]`
+
+### Fields the agent MUST fill
+
+- `title`
+- at least one actor
+- each step: `id`, `name`, `type`
+- each transition: `from_step_id` or `from`, `to_step_id` or `to`, `label`
+- at least one summary card
+- at least one review instruction
+
+### Fields that may fallback
+
+- `locale`
+- `subtitle`
+- step `lane`
+- step `description` / `subtitle`
+- step `details`
+- `openQuestions`
+- `metadata.*`
+
+Use fields such as:
+
+- `locale`
+- `flowName`
+- `description`
+- `actors[]`
+- `steps[]`
+  - `id`
+  - `name`
+  - `type`
+  - `description`
+  - `lane`
+- `decisions[]`
+- `transitions[]`
+- `happyPath[]`
+- `errorPaths[]`
+- `assumptions[]`
+- `openQuestions[]`
+- `reviewInstructions[]`
+
+## Current Runtime Reality
+
+Current OpenPrd CLI has a built-in renderer for:
+
+- `openprd diagram`
+
+This is currently architecture-oriented.
+
+If the user needs a product-flow view:
+
+- still create the product-flow contract
+- do not claim there is a dedicated flow renderer if there is not
+- use the contract as the review artifact or as the next implementation target

package/skills/openprd-diagram-review/references/review-checklist.md

@@ -0,0 +1,10 @@
+# Diagram Review Checklist
+
+Ask the user to confirm:
+
+1. Are any components or steps missing?
+2. Are any boundaries, swimlanes, or ownership splits wrong?
+3. Are any external dependencies missing?
+4. Are any decision points, failure paths, or review/sign-off points missing?
+5. Are any labels wrong or in the wrong language?
+6. Is this complete enough to support freeze, or should the diagram be revised first?

package/skills/openprd-discovery-loop/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: openprd-discovery-loop
+description: 把自然语言里的 OpenPrd 或 OpenSpec 深度、持续、全面、参考挖掘、需求发现类请求，路由到 OpenPrd 的长程 discovery 工作流。适用于继续推进、深度分析、全面补齐、对标复刻或完善 requirements、specs 和 tasks 的场景。
+---
+
+# OpenPrd Discovery Loop
+
+## 概览
+
+当用户要求 OpenPrd 持续推进、深度补全、完整覆盖或穷尽式梳理需求覆盖时，使用这份 skill。OpenSpec 仍然是支持的输出格式和兼容词汇，但 OpenPrd 才是负责路由、生成、校验和任务执行的主入口。
+
+用户不需要知道 skill 名称或 CLI 参数。你要根据自然语言意图判断模式，再调用对应的 OpenPrd 内部命令。
+
+## 自然语言触发词
+
+当用户把 OpenPrd 或 OpenSpec 和这些意图词连在一起时，路由到这里：
+
+- 持续、继续、一直推进、不断补全、长程
+- 深度、深挖、深入梳理、深入分析
+- 全面、完整、全量、穷尽、尽可能覆盖
+- 大量扫描、只读扫描、跨模块证据收集、独立复核
+- 补全、完善、生成规范、生成 OpenSpec、整理成任务
+- 复刻、对标、参考这个项目、把这个项目逻辑转成规范
+
+应该命中本 skill 的示例：
+
+- “用 OpenPrd 深度补全这个项目。”
+- “用 OpenSpec 深度补全这个项目。”
+- “全面梳理现有项目，把规范和任务补齐。”
+- “参考这个仓库，持续复刻它的产品逻辑到新项目。”
+- “继续深挖这个需求，直到覆盖完整。”
+
+不要要求用户显式说出 `Use $openprd-discovery-loop`。
+
+## 模式
+
+- `brownfield`：检查现有项目，并把发现到的行为补充进覆盖项
+- `reference`：检查参考项目，并把产品逻辑翻译成当前项目的 requirements、specs 和 tasks
+- `requirement`：持续追问和细化一个需求，直到它具备足够的范围、约束、流程、风险、验收标准和可执行任务
+
+## 自动模式选择
+
+替用户选模式：
+
+- 当用户提供 GitHub 仓库、本地参考路径，或明确说复刻 / 对标 / 参考 / clone / parity 时，选 `reference`
+- 当目标是现有本地项目，且用户要求深度补全 / 全面梳理 / 扫描 / 完善时，选 `brownfield`
+- 当输入主要是想法、模糊请求、产品需求或功能概念，且没有单独参考项目时，选 `requirement`
+
+如果意图混合：优先 `reference`；没有参考项目但有本地代码时优先 `brownfield`；两者都没有再用 `requirement`
+
+## 大量只读扫描调度
+
+当 OpenPrd discovery 需要大量只读扫描时，由主 agent 判断是否派发只读 subagent。日常任务仍由主 agent 先直接读取本地上下文；不要因为用户只说“看看、分析、梳理、定位、排查”就自动并行。
+
+### 启动条件
+
+- 用户明确要求深度分析、深入调研、全面梳理、多角度评估、交叉验证、并行排查、对标复刻或风险审查时，优先考虑只读 subagent。
+- 任务需要同时阅读多个目录、文档、模块、日志、历史实现或参考项目，且并行收集证据能明显减少主上下文污染或节省时间时，可以启动。
+- 任务涉及外部技术事实、公开仓库对标、复杂排障、发布风险或安全风险，且需要独立复核时，可以启动；仍必须遵守 Context7、DeepWiki、secrets-vault 和长文件门禁。
+- 用户明确说“不用 subagent / 直接做 / 先别并行 / 只回答”时，不启动。
+- 单文件小改、明确文案微调、简单命令、非常短的问题或清晰 bug 修复，默认不启动。
+
+### 默认队形
+
+- 一旦进入深度研究型 subagent 流程，默认使用 3 个只读 subagent：2 个独立调研执行者 + 1 个审查/交叉验证者。
+- 最多启动 5 个 subagent：最多 4 个调研执行者 + 1 个审查者。只有任务天然拆成 4 个互不冲突的研究分支时才扩到 5 个。
+- 每个 subagent 只回答一个清晰问题；不要让 subagent 再继续 spawn subagent。
+- 主 agent 负责决策、整合和所有写入；subagent 只做快读、快扫、归纳、交叉验证，不直接修改文件、执行迁移、安装依赖、发布、提交表单、账号操作或删除文件。
+- 主 agent 可以在 subagent 后台运行时继续做不冲突的本地工作；只有下一步确实依赖其结论时才等待。
+
+### 角色选择
+
+- 代码与文档调研：`spark-code-researcher`、`spark-doc-reader`、`documentation-explore`
+- 对标复刻前置分析：`electron-parity-mapper`
+- 安装、构建、发布或渠道排障：`release-diagnostics-researcher`、`channel-debug-researcher`
+- 审查与风险扫描：`skill-workflow-reviewer`、`security-risk-researcher`
+
+其余细分 agent 只在任务已经命中明确工作流时使用，例如离职交接和 Rollbar crash team。不要为一次性、小范围、单文件任务新增 agent 或强行并行。
+
+### 证据合并
+
+- 调研分支要拆分清楚范围，避免多个 subagent 研究同一批文件。
+- subagent 输出必须回到主 agent 汇总；不能把 subagent 推断直接当成最终结论。
+- 写入 discovery claim、requirements、specs 或 tasks 前，主 agent 必须把结论映射到证据路径、置信度和未解决问题。
+- 审查者负责检查证据是否充分、是否遗漏关键风险、是否违反 Context7、DeepWiki、secrets-vault、长文件和写入门禁；审查者不替代主 agent 决策。
+
+## 动手前
+
+1. 读取第一份可用的 OpenPrd 共用规则：
+   - `skills/openprd-shared/SKILL.md`
+   - `$HOME/.claude/skills/openprd-shared/SKILL.md`
+   - `$HOME/.codex/skills/openprd-shared/SKILL.md`
+2. 除非用户只是在问原理，否则先运行或检查 `openprd status` 和 `openprd next`
+3. 需要 hook-stable 执行时，运行：
+   - `openprd run <path> --context`
+   - 再执行推荐的 task、discovery 或 workflow 命令
+   - `openprd run <path> --verify`
+4. 如果 `.openprd/discovery/current.json` 不存在，用选定模式初始化：
+   - `openprd discovery <path>`
+   - `openprd discovery <path> --mode reference --reference <path>`
+   - `openprd discovery <path> --mode requirement`
+5. 如果已有运行状态，就继续：
+   - `openprd discovery <path> --resume`
+6. 每轮覆盖之后，用下面命令推进或校验：
+   - `openprd discovery <path> --advance --item <id> --claim <text> --evidence <path>`
+   - `openprd discovery <path> --advance --item <id> --status blocked --notes <text>`
+   - `openprd discovery <path> --verify`
+7. 当 PRD 需要变成具体 change 文件时，运行：
+   - `openprd change <path> --generate --change <id>`
+8. 只有在需要单独检查 change 结构时，才运行 `openprd change <path> --validate --change <id>`；通常 discovery verify 在配置了 `activeChange` 时会一并检查
+9. 报告发现结果就绪前，运行 `openprd standards <path> --verify`
+10. 阶段性实现或任务完成后，运行 `openprd quality <path> --verify`，让 HTML 质量评估报告审查日志、业务护栏、冒烟覆盖、功能覆盖、性能基线、极端数据和知识缺口
+11. 修改文档或任务前，先从当前 run 目录重新读取状态
+
+## 运行目录
+
+每次 run 会写入：
+
+- `control.json`：当前模式、迭代、预算、来源根目录和下一步动作
+- `context.md`：下一轮要用的紧凑状态摘要
+- `source-inventory.json`：索引后的项目或参考文件
+- `coverage-matrix.json`：待处理、已覆盖和已阻塞的覆盖项
+- `claims.jsonl`：带证据的需求 claim
+- `open-questions.md`：需要保持可见的未决问题
+- `iterations.jsonl`：每一轮推进的追加记录
+
+hook harness 还会写入：
+
+- `.openprd/harness/run-state.json`：当前循环摘要和上一条建议
+- `.openprd/harness/iterations.jsonl`：hook turn 记录、门禁结果和 run 校验
+- `.openprd/harness/learnings.md`：跨新会话保留的可复用经验
+
+当前存储路径是 `.openprd/discovery`。历史 `.openspec/discovery` 状态仍可兼容读取，但新工作应写入 OpenPrd 自己的 discovery 状态。
+
+## 工作循环
+
+1. 从 `coverage-matrix.json` 选择下一个待处理项
+2. 写入新 claim 前，先收集本地证据
+3. 只用已确认或有证据支撑的材料更新文档或任务
+4. 每条新事实都写入 `claims.jsonl`，附带来源和置信度
+5. 把覆盖项标记为 covered、pending 或 blocked
+6. 把本轮摘要追加到 `iterations.jsonl`
+7. 只有当覆盖耗尽、被阻塞，或达到迭代预算时才停止
+
+## 任务分片
+
+大型 change 必须保持对 agent 易读、易恢复：
+
+- `tasks.md` 始终是第一份也是标准任务入口
+- 每个任务文件最多保留 25 个有实质内容的 checkbox 任务
+- 项目可以在 `.openprd/discovery/config.json` 里通过 `taskSharding.maxItemsPerFile` 设更严格上限
+- 如果任务更多，就继续写 `tasks-002.md`、`tasks-003.md` 等同级文件
+- 每个非最终任务文件的最后一个 checkbox 都必须交接到下一个文件，例如：
+  - `[ ] Continue with tasks-002.md after completing this file.`
+- 尽量把相关章节放在一起，不要为了凑行数硬拆强耦合功能
+- 稳定的长程任务只使用 `deps`、`done` 和 `verify` 元数据：
+  - `[ ] T009.07 Port legacy database import preview`
+  - `  - deps: T001.14, T007.06`
+  - `  - done: preview shows counts, conflicts, skipped items, warnings`
+  - `  - verify: npm run test -- migration`
+- 没有依赖时省略 `deps`；来源证据保留在 discovery claims 和 coverage 文件中
+- 报告 discovery 状态健康前，运行 `openprd discovery <path> --verify`。它会校验 discovery 状态、激活的 change 结构、spec delta、`docs/basic/` standards、任务分片和结构化任务依赖
+
+## CLI 推进规则
+
+- 在一个覆盖项调查完之后再用 `--advance`
+- 用 `--claim` 记录发现到的 requirement、行为、规则或验收标准
+- 当 claim 来自文件时，用 `--evidence`
+- 当条目暂时无法解决时，用 `--status blocked --notes ...`
+- 在报告 run 健康或进入评审前，用 `--verify`
+
+## 任务执行
+
+- 使用 `openprd tasks <path> --change <id>` 查看进度和下一个依赖已满足的任务
+- 当某项任务已经可以通过自己的 `verify` 命令完成时，使用 `openprd tasks <path> --change <id> --advance --verify --item <task-id>`
+- 使用 `openprd change <path> --apply --change <id>` 把完成的 change specs 推进到 `openprd/specs`
+- 使用 `openprd change <path> --archive --change <id>` 把完成的 change 文件移动到 `openprd/archive/changes`
+- 当任务或 discovery pass 改动了基线文档、文件说明书或文件夹 README 时，运行 `openprd standards <path> --verify`
+- 在声明任务实现就绪前，运行 `openprd quality <path> --verify`；当某个已验证修复应该沉淀为项目级复用经验时，运行 `openprd quality <path> --learn --from <report>`
+- 如果任务被依赖阻塞，先完成更早的任务 id；不要人工跳过依赖顺序
+- 执行证据应保留在生成的任务事件或 discovery claims 中，不要给每个任务额外挂一堆元数据
+
+## 证据规则
+
+- 来自代码、测试、schema 或文档的 claim 应包含来源文件路径
+- 由 agent 推断出来的 claim 必须显式标为 inferred，并保持可评审
+- 用户确认过的答案应保留为 user-confirmed claim
+- 不要把未解决问题悄悄改写成 requirements
+
+## 安全默认值
+
+- 优先做小而高置信的更新，不做大而猜测性的重写
+- 证据薄弱时，让覆盖缺口保持可见
+- 面对参考项目时，优先描述行为和验收标准，不要复制实现细节
+- 当下一步需要用户判断时，把它写进 `open-questions.md`，并明确报告 blocker
+- 项目基线文档路径只能是 `docs/basic/`

package/skills/openprd-discovery-loop/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: openprd-discovery-loop
+short_description: "Continuously mine and complete OpenPrd requirements, specs, and tasks"
+default_prompt: "Route natural-language OpenPrd/OpenSpec deep, continuous, comprehensive, or reference-mining requests into OpenPrd's long-running discovery workflow."

package/skills/openprd-harness/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: openprd-harness
+description: 驱动 OpenPrd 工作区完成从澄清到 handoff 的主流程。适用于初始化 OpenPrd、查看 `.openprd/` 状态、选择下一条命令、推进 classify/interview/synthesize/freeze/handoff，或解释如何安全推进 OpenPrd 工作区。
+---
+
+# OpenPrd Harness
+
+## 概览
+
+这份 skill 负责主工作流编排。把它当成串起命令和产物的领域 skill；共用守则由 `$openprd-shared` 提供。
+
+`AGENTS.md` 只保留轻量合同；入口路由优先看 `skills/openprd-router/SKILL.md`，具体命令速查看 `.openprd/harness/command-catalog.md`，更细的工作流步骤、路由边界和 hook 门禁以这份 skill、`$openprd-shared` 和 `$openprd-benchmark-router` 为准。
+
+执行时优先继承 `$openprd-shared` 的用户心智与表达规则：用户懂业务和产品，但不想读技术黑话；默认耐心低、成本敏感，需要 Agent 主动补全遗漏，并用最短路径说明结论和下一步。
+
+## 动手前
+
+1. 读取第一个可用的共用规则文件：`skills/openprd-shared/SKILL.md`、`$HOME/.claude/skills/openprd-shared/SKILL.md` 或 `$HOME/.codex/skills/openprd-shared/SKILL.md`
+2. 从 `.openprd/` 重建当前工作区状态
+3. 如果用户期待自动化 agent 引导，运行 `openprd doctor <path>`，必要时用 `openprd setup <path>` 或 `openprd update <path>` 修复
+4. 选择执行单元前，优先运行 `openprd run <path> --context`
+5. 把 `openprd run <path> --context` 当作建议，不要自动执行其中的写入命令
+   - 如果用户给出会话 ID 并要求继续，按工具无关的历史会话精确续接；不要要求或使用工具专属 ID，也不要用当前 active change、相似历史或当前 requirement gate 替代该会话 ID
+   - 如果用户没有给 ID，但明确描述了某个已有需求、change、task 或 work unit，先把这段描述交给 `openprd run <path> --context --message <用户原话>` 做显式对象解析，不要先默认拿当前 active change
+6. 需求复杂度先交给 `$openprd-requirement-intake` 分流；不要按固定关键词判断。它会根据影响面、未知数、决策成本和验证成本判断 L0 小修、L1 mini-plan 或 L2 PRD/review/change/tasks
+7. 如果用户是在规划、分析、架构评审，或问“怎么改”“会动哪些文件”，保持只读并基于证据回答
+8. 实现任务完成代码修改后、最终回复前，针对本轮实际 touched code files 运行 `openprd dev-check <path> <file...>` 或 `node scripts/openprd-dev-check.mjs <path> <file...>`：700 行以内正常；701-1500 行需说明局部职责；超过 1500 行要判断本轮是否扩大职责，扩大则先重构/拆分/解耦并复查，窄 bugfix 或小修暂不拆时说明原因和后续拆分建议
+9. 执行过程中发现新代码后缀、豁免路径、命令别名、项目约定或用户偏好时，不要中途打断当前任务。工具识别补全和减少重复打扰这类高置信低风险项可自动补齐并记录；用户偏好、项目协作规矩和 OpenPrd 默认行为先沉淀为候选，收工时运行 `openprd grow <path> --review` 集中确认
+10. 维护 OpenPrd 本身时，只要新增或修改配置类能力（阈值、规则、识别、豁免、命令别名、环境差异、用户偏好或策略开关），默认先做 grow-aware 自检：高置信应可成长时直接纳入 `openprd grow` 体系；不确定时主动询问用户是否做成可成长配置
+11. 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup、先看样子或先确认设计方向时，默认直接调用 Codex 原生 Image 2 生图能力产出图片；除非用户明确指定 HTML、SVG、CSS、Canvas、代码稿或可编辑矢量/source artifact，不要改用临时 HTML/SVG/CSS 再截图。OpenPrd 的 `review.html` 只用于需求评审，不能替代图片或效果图生成
+12. 界面、页面、视觉、样式或前端体验任务中，如果已经有效果图、设计稿、图片资产、截图或用户给图且进入实现阶段，阶段性完成后先截实现图，再运行 `openprd visual-compare <path> --reference <效果图> --actual <实现截图>`。默认输出 JPG 到 `.openprd/harness/visual-reviews/`，左侧标注“效果图”、右侧标注“实现截图”；查看合成图后继续复刻，直到没有明显视觉差异
+13. 实现任务新增或修改文件时，做文档影响检查：缺失的 `docs/basic/`、文件说明书、文件夹 README 要补齐；受影响的已有文档要更新；涉及后端、脚本、Agent、工具链、服务或数据处理变更时，把 CLI 与 API 视为同级接入面，更新 `docs/basic/backend-structure.md` 中的命令入口、输出契约、`help`/`doctor`/`dry-run`/`status`、接口协议与不适用说明
+14. 长时间实现任务使用 `openprd loop <path> --plan --change <id>`，并且只有当前用户消息明确要求开发、继续任务、深度调研、对标复刻或提交时，才为每个 loop 任务启动一个全新 agent 会话
+15. 需要完整工作流细节时，使用 `openprd status` 和 `openprd next`
+16. 用户要求最佳实践、benchmark、对标、参考产品、prompt engineering、Agent harness、context engineering、图标资源、CLI 或 skill 体系设计时，先路由到 `$openprd-benchmark-router`
+17. 用户要求基线文档、文件说明书、文件夹 README 标准或实现就绪检查时，路由到 `$openprd-standards`
+18. 用户要求日志、链路追踪、业务成本护栏、免费额度、滥用防护、评估执行环境、冒烟覆盖、性能基线、极端场景、HTML 质量评估报告或项目级经验 Skill 时，路由到 `$openprd-quality`
+19. 用户需要可视化说明，或系统/产品形态仍不清晰时，在进入需求定稿前路由到 `$openprd-diagram-review`
+20. 默认保持 Codex hooks 轻量。除非项目明确需要完整工具级遥测，否则 `openprd setup/update` 使用 `--hook-profile lite`；默认 `lite` 会保留 `Stop` 收工回顾，用于在本轮结束前提醒是否值得沉淀项目经验
+21. hook 会强制阻断几类场景：需求入口未完成就写实现、外部证据不足就直接改第三方集成、skill/AGENTS 变更未先可视化确认、以及敏感信息场景下直接读原始 vault 文件
+22. 当 `doctor` 报告生成引导漂移时，读取 `.openprd/harness/drift-report.json`
+
+## 主工作流
+
+### 1. 初始化或定位工作区
+
+- 如果 `.openprd/` 不存在，使用：
+  - `openprd init <path> --template-pack <base|consumer|b2b|agent>`
+- `init` 会同时创建 standards 和 agent integration，包括 Codex、Claude、Cursor 的生成引导、项目级 Codex hooks 和用户级 Codex hooks feature flag
+- `init` 也会创建质量状态，包括 `.openprd/quality/config.json`、`.openprd/quality/reports/` 和 `.openprd/knowledge/`
+- `init` 也会创建自我成长候选队列，包括 `.openprd/growth/candidates.jsonl`、`accepted.json`、`rejected.json` 和本地偏好文件
+- 如果 standards 缺失，或用户要求修复：
+  - `openprd standards <path> --init`
+- 如果生成的 agent 引导或 hooks 缺失：
+  - `openprd setup <path>`
+  - `openprd doctor <path>`
+- 如果生成引导存在但漂移了：
+  - `openprd update <path>`
+  - `openprd doctor <path>`
+- hook 驱动执行循环使用：
+  - `openprd run <path> --context`
+  - `openprd run <path> --verify`
+  - 让 `.openprd/harness/run-state.json`、`iterations.jsonl` 和 `learnings.md` 成为持久循环状态
+  - 不要把 `run --context` 建议当作直接用户命令
+  - 用户给出会话 ID 续接历史任务时，使用 `openprd run <path> --context --message <用户原话或会话ID>` 保留通用会话 ID 语义；先恢复指定会话，不要让当前 active change 抢主线
+  - 用户没有给 ID、但明确描述了已有需求/任务对象时，也使用 `openprd run <path> --context --message <用户原话>`；先解析对应的 change/task/work unit，再决定是否沿用当前工作区状态
+  - 默认 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 信号回顾是否要生成项目经验草案
+  - 只有当项目确实需要完整 hook 遥测或临时深度诊断时，才用 `openprd update <path> --hook-profile full`
+- 长程实现循环使用：
+  - `openprd loop <path> --init`
+  - `openprd loop <path> --plan --change <id>`
+  - `openprd loop <path> --next`
+  - `openprd loop <path> --prompt --agent codex`
+  - `openprd loop <path> --run --agent codex --dry-run`
+  - `openprd loop <path> --run --agent claude --dry-run`
+  - `openprd loop <path> --finish --item <task-id> --commit`
+  - 让 `.openprd/harness/feature-list.json`、`progress.md`、`agent-sessions.jsonl`、`loop-state.json` 和 `loop-prompts/` 成为持久实现状态
+  - 只有在当前用户消息明确要求开发、继续任务、深度调研、对标复刻或提交时，才运行 `openprd loop <path> --run`
+  - 代码修改完成后、最终回复前，运行 `openprd dev-check <path> <file...>`；attention/warning 必须在最终回复里说明是否局部处理、是否已拆分，或为什么窄修暂不拆
+  - 用户只是要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup 或先看样子时，默认调用 Codex 原生 Image 2 生成图片；除非用户明确指定 HTML/SVG/CSS/Canvas/代码稿，不要生成临时 HTML 再截图
+  - 如果已有参考效果图、图片资产、设计稿、截图或用户给图并进入实现阶段，阶段性完成后必须生成实现截图，并用 `openprd visual-compare <path> --reference <效果图> --actual <实现截图>` 输出 JPG 视觉对比图。未查看对比图、或对比图仍有明显差异时，不要声称界面复刻完成
+  - `openprd loop <path> --finish` 前，先完成文档影响检查并更新缺失或过期的 `docs/basic/`、文件说明书和文件夹 README；涉及后端、脚本、Agent、工具链、服务或数据处理变更时，同步评估 CLI 与 API 两个接入面
+  - 声称任务就绪前，运行 `openprd quality <path> --verify` 并审阅生成的 HTML 质量评估报告，检查场景标签、必需 EVO 门禁、日志、业务护栏、冒烟覆盖、任务完整性、性能基线、极端场景和知识缺口
+  - 如果本轮修复已经出现可复用模式，可先运行 `openprd quality <path> --learn --review --from .openprd/harness/turn-state.json` 生成 knowledge candidate / draft skill；确认值得长期保留后，再运行 `openprd quality <path> --learn --from <candidate-dir>` promote 为正式项目经验
+  - `openprd loop <path> --finish` 应同时留下 Markdown 和 HTML 回归证据到 `.openprd/harness/test-reports/`，把它们视作任务交付物的一部分
+  - 每个 loop 任务都对应一个全新 Codex 或 Claude 会话边界，不要在同一会话里继续下一项任务
+- 处理历史项目集群前先审计：
+  - `openprd fleet <root> --dry-run`
+  - `openprd fleet <root> --update-openprd`
+  - 除非用户明确要求 OpenPrd 接管 agent-only/plain 项目，否则不要使用 `--setup-missing`
+- 如果工作区已经存在，先检查再写入
+- 初始化后不要立刻跳到 synthesize，优先做明确澄清
+
+### 2. 与用户澄清
+
+- 使用：
+  - `openprd clarify <path>`
+- 当关键产品事实缺失时，先查看 `intake-reflection.md` 的需求入口自省，再把压缩后的必须确认问题问给用户
+- 当需求模糊、起点只有一句想法，或需要先做方案探索时，先查看生成的 `intake-reflection.md`，再把压缩后的目标、范围、非目标、验收方式和必须确认问题放在对话里请用户确认；不要生成或打开澄清 HTML
+- 优先分阶段确认：问题、用户、范围、成功标准和开放问题；复杂需求先让 OpenPrD 内部完成意图归一化、项目上下文映射和产品质量自检，不要把固定问题墙一次性砸给用户
+- 收到答案后，用下面命令写回：
+  - `openprd capture <path> --field <section.path> --value <text|json>`
+- 当你是在追加列表型字段，而不是整体替换时，使用 `--append`
+
+### 3. 锁定产品类型
+
+- 如果 `productType` 缺失，运行：
+  - `openprd classify <path> <consumer|b2b|agent>`
+
+### 4. 加载澄清提示
+
+- 如果必填字段仍缺失，使用：
+  - `openprd interview <path> --product-type <type>`
+- 未解决的问题要保持可见，不要假装 intake 已经完整
+
+### 5. 生成可评审草稿
+
+- 使用：
+  - `openprd synthesize <path> --title ... --owner ... --problem ... --why-now ...`
+- 如果草稿仍然稀疏，明确说明还缺什么
+- `synthesize` 生成 `review.html` 后，必须把 HTML 路径告诉用户，并自动打开它（或紧接着运行 `openprd review <path> --open`）
+- 评审页里的需求关系图、需求流程图和重点摘要不要靠 HTML 截断；`openprd synthesize` 生成版本快照后，不要直接把 review 给用户确认。必须先用 `openprd review-presentation <path> --template` 查看展示文案契约，让 Agent 按 `reviewPresentation` 写短文案，再用 `openprd review-presentation <path> --presentation <json> --write --fail-on-violation` 校验并写回。脚本通过后会写入校验元信息并重渲染可确认 review.html；超限时按脚本返回的 jsonPath 和字数限制重新提炼，不手工改快照、不裁剪原文
+- 把生成的 `review.html` 当作首选稳定评审 artifact。默认 approval policy 是 `decision-points`：当前 lane 仍需要人类决策时，请用户先评审问题定义、范围、主流程、风险和开放问题，再运行带精确 `--version`、`--digest`、`--work-unit` 的 `openprd review <path> --mark confirmed`。若用户一开始已经明确要求直接做，并显式表示不需要额外评审或确认，lane 可进入 `silent-record`，这时只允许记录当前精确匹配的稳定 artifact，不能借机替别的版本补确认。review 记录完成且 tasks 就绪后，如果用户原始意图已经明确要求实现，可直接继续执行；否则等待一句明确的执行指令
+
+### 6. 需要时生成可视化评审产物
+
+- 当用户需要以下内容时，路由到 `$openprd-diagram-review`：
+  - 架构确认
+  - 流程 / 旅程确认
+  - 需求定稿前的可视化评审
+
+### 7. 只在草稿准备好时 freeze
+
+- 使用：
+  - `openprd freeze <path>`
+- Freeze 是门禁，不只是另一次渲染
+- 声称实现就绪前，先校验 standards：
+  - `openprd standards <path> --verify`
+  - 这不只是缺文件检查；对已变更文件，还要判断现有文档是否过期，并在必要时更新
+- 声称实现就绪前，再校验质量：
+  - `openprd quality <path> --verify`
+  - 把 `.openprd/quality/reports/<id>.html` 当作面向人的评审产物，用于查看当前场景必需 EVO 门禁、可观测性、业务成本与滥用护栏、评估执行环境、性能、压力数据和项目知识
+  - 如果 HTML 或 `openprd run <path> --verify` 显示 `productionReady=false`，最终回复不得宣称就绪；必须列出缺证据或需关注的必需门禁
+- 进入高风险动作前，校验完整 harness：
+  - `openprd run <path> --verify`
+  - `openprd doctor <path>`
+
+### 8. 导出 handoff 包
+
+- 使用：
+  - `openprd handoff <path> --target openprd`
+
+## 安全默认值
+
+- 当下一步存在歧义时，优先用 `openprd next`
+- 当任务属于一般执行循环时，优先用 `openprd run --context`
+- 当任务是需要拆成“每个任务一个全新 agent 会话”的实现工作时，优先用 `openprd loop --plan` 和 `openprd loop --run --dry-run`
+- 当用户要求“看看、规划、梳理、分析、评估、explain、review”或列出影响文件时，优先保持只读检查
+- 除非当前用户消息明确要求执行，否则不要运行 `openprd loop --run`、`openprd tasks --advance`、`openprd discovery --advance`、`openprd loop --finish --commit`、git commit 或 git push
+- 当 agent 环境可能没有正确跟随 OpenPrd 时，优先用 `openprd doctor`
+- 生成 adapter 文件漂移时，优先运行 `openprd update` 修复，而不是手改生成文件
+- 当方案形态仍不清晰时，优先先 review 再进入需求定稿
+- 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup 或先看样子时，优先调用 Codex 原生 Image 2；界面任务已有参考图并进入实现阶段时，才用 `openprd visual-compare` 生成左右对比 JPG，作为视觉就绪判断依据
+- 遇到 blocker 时，优先把阻塞条件显式暴露出来，而不是悄悄补脑
+
+## 禁止行为
+
+- 不要发明不存在的命令
+- 不要因为 CLI 技术上允许，就在用户还没确认方案结构时直接进入需求定稿
+- 当图示评审或草稿评审明显仍有必要时，不要 handoff 一个用户尚未审阅的工作区
+- 项目基线文档路径只能是 `docs/basic/`
+- 当 `openprd setup`、生成规则和 hooks 已经可以引导 agent 时，不要反过来要求用户记住具体 skill 名
+
+## 需要时阅读这些参考资料
+
+- `references/command-map.md`：命令到意图的映射
+- `references/workflow-gates.md`：门禁判断和就绪规则
+- `references/examples.md`：具体使用模式
+- `references/usage-guide.md`：面向团队和 agent 的使用指南，覆盖 clarify、diagram、freeze、status/next 和批量 capture

package/skills/openprd-harness/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenPrd Harness"
+  short_description: "Run the full OpenPrd workflow with safe defaults"
+  default_prompt: "Use $openprd-harness to drive an OpenPrd workspace from clarification through handoff."

package/skills/openprd-harness/examples/full-workflow-zh.md

@@ -0,0 +1,9 @@
+用户请求：
+帮我把这个产品需求推进到可以 handoff 的状态。
+
+期望行为：
+- 先重建 OpenPrd workspace 状态
+- 用 next/status 判断当前阶段
+- 缺少澄清时走 interview
+- 需要视觉确认时路由到 $openprd-diagram-review
+- freeze 和 handoff 都保持门禁意识

package/skills/openprd-harness/references/command-map.md

@@ -0,0 +1,71 @@
+# OpenPrd Command Map
+
+## Core Lifecycle
+
+1. `openprd init`
+2. `openprd clarify`
+3. `openprd capture`
+4. `openprd classify`
+5. `openprd interview`
+6. `openprd synthesize`
+7. `openprd diagram`
+8. `openprd freeze`
+9. `openprd handoff`
+10. `openprd change`
+11. `openprd changes`
+12. `openprd specs`
+13. `openprd tasks`
+14. `openprd discovery`
+15. `openprd standards`
+16. `openprd setup`
+17. `openprd update`
+18. `openprd doctor`
+19. `openprd run`
+
+## Read / Inspect
+
+- `openprd status`
+- `openprd validate`
+- `openprd next`
+- `openprd history`
+- `openprd diff`
+- `openprd standards --check`
+- `openprd standards --verify`
+- `openprd doctor`
+- `openprd run --context`
+- `openprd run --verify`
+
+## Routing Heuristics
+
+- no workspace -> `init`
+- missing key user-confirmed facts -> `clarify`
+- user answers available -> `capture`
+- no product type -> `classify`
+- missing required fields after clarification -> `interview`
+- draft needed -> `synthesize`
+- structure unclear or user asks for visuals -> diagram review
+- ready and validated -> `freeze`
+- execution transfer needed -> `handoff`
+- PRD snapshot should become concrete OpenPrd change files -> `change --generate --change <id>`
+- OpenPrd coverage needs sustained discovery -> `discovery`
+- user says OpenPrd or OpenSpec plus 持续 / 深度 / 全面 / 复刻 / 对标 / 补全 -> route to OpenPrd discovery mode
+- one coverage item has evidence -> `discovery --advance`
+- discovery state needs a health check -> `discovery --verify`
+- project baseline docs or manual standards need setup -> `standards --init`
+- docs/basic, file manual, or folder README standards need checking -> `standards --verify`
+- agent rules, commands, or hooks need installing -> `setup`
+- generated rules or hooks may be stale -> `update`
+- Codex/Claude/Cursor guidance health is uncertain -> `doctor`
+- hook-driven execution unit is needed -> `run --context`
+- hook-driven loop needs gate validation -> `run --verify`
+- long-running implementation needs one fresh agent session per task -> `loop --plan --change <id>`, then `loop --run --agent codex|claude --dry-run`
+- one long-running task was completed and verified -> `loop --finish --item <task-id> --commit`
+- change structure needs isolated validation -> `change --validate --change <id>`
+- accepted specs need promotion -> `change --apply --change <id>`
+- completed change should be moved out of active work -> `change --archive --change <id>`
+- multiple changes need inspection -> `changes`
+- accepted baseline specs need inspection -> `specs`
+- next implementation task is needed -> `tasks --change <id>`
+- a structured task is ready to complete -> `tasks --change <id> --advance --verify --item <task-id>`
+- tasks exceed 25 substantive checkbox items -> shard as `tasks.md`, `tasks-002.md`, `tasks-003.md`, then verify
+- stable long-running tasks need metadata -> use only `deps`, `done`, and `verify`