@openprd/cli 0.1.0

package/skills/openprd-harness/references/examples.md

@@ -0,0 +1,26 @@
+# Example Requests
+
+## Example 1
+
+User:
+
+> 用 OpenPrd 帮我把这个 AI 教学产品从需求澄清推进到可以 handoff 的状态。
+
+Expected routing:
+
+- use `openprd status`
+- use `openprd next`
+- continue through classify/interview/synthesize
+- route to `$openprd-diagram-review` before freeze if the structure is still unclear
+
+## Example 2
+
+User:
+
+> 这个工作区现在应该先 freeze 还是先补图？
+
+Expected routing:
+
+- inspect current state
+- inspect next/blockers
+- if system shape still needs confirmation, recommend diagram review first

package/skills/openprd-harness/references/usage-guide.md

@@ -0,0 +1,335 @@
+# OpenPrd 使用指南
+
+这份指南是给 **团队成员** 和 **Agent** 的 OpenPrd 实战使用说明。重点不是命令表，而是：
+
+- 什么时候先 `clarify`
+- 什么时候先 `diagram`
+- 什么时候检查 `standards`
+- 什么时候可以直接 `freeze`
+- `status` / `next` 该怎么看
+- `batch capture` 怎么用
+
+## 一、先判断你处于哪种场景
+
+OpenPrd 现在会区分 3 种场景：
+
+### 1. Cold start (greenfield)
+
+特点：
+
+- 项目目录基本是空的
+- `.openprd/` 刚初始化
+- 没有现成产品上下文可复用
+
+协同方式：
+
+- 高协同
+- 先问用户
+- 不要自己先写完整 PRD
+
+优先动作：
+
+- `openprd clarify`
+- 根据用户回答 `openprd capture`
+
+### 2. Cold start (existing project)
+
+特点：
+
+- 项目已有 README / docs / 代码 / 现成能力
+- `.openprd/` 是第一次接入
+
+协同方式：
+
+- 先复用现有上下文
+- 但关键产品事实必须让用户确认
+
+优先动作：
+
+- `openprd status`
+- `openprd clarify`
+- 用 `openprd capture --source project-derived` 导入已有事实
+- 用 `openprd capture --source user-confirmed` 写回用户确认
+- 用 `openprd standards <path> --verify` 检查 `docs/basic/` 和说明书模板
+
+### 3. Continuing workspace
+
+特点：
+
+- 已有 `.openprd/` 历史
+- 已经 synthesize / freeze / handoff 过
+
+协同方式：
+
+- 只做增量澄清
+- 不重跑全量初始化
+
+优先动作：
+
+- `openprd status`
+- `openprd next`
+- 只补变化部分
+- 每次功能落地前检查 `openprd standards <path> --verify`
+
+---
+
+## 二、什么场景先 `clarify`
+
+优先 `clarify` 的情况：
+
+- 项目刚初始化
+- 关键产品字段缺失
+- 用户的目标、范围、成功标准还不清楚
+- 虽然 repo 有内容，但你还不能判断“这次 OpenPrd 到底定义什么”
+- 你手上只有技术上下文，没有用户确认
+
+### 典型信号
+
+如果 `openprd next` 或 `openprd status` 显示：
+
+- `Current gate: clarify-user`
+
+那么不要继续往 `synthesize`、`diagram`、`freeze` 推进。
+
+### 推荐操作
+
+```bash
+openprd clarify <path>
+```
+
+然后把用户回答写回：
+
+```bash
+openprd capture <path> --field problem.problemStatement --value "..."
+openprd capture <path> --field goals.successMetrics --value "..."
+```
+
+---
+
+## 三、什么场景先 `diagram`
+
+优先 `diagram` 的情况：
+
+- 需求的**系统边界**需要确认
+- 依赖、模块、数据/控制流复杂
+- 用户流程、决策点、失败路径复杂
+- freeze 前需要一个 visual artifact 来做协同确认
+
+### 什么时候画 architecture
+
+适用于：
+
+- 模块边界
+- 服务依赖
+- control plane / data plane 分工
+- 权限、审核、可靠性边界
+
+```bash
+openprd diagram <path> --type architecture
+```
+
+### 什么时候画 product-flow
+
+适用于：
+
+- onboarding
+- 用户操作步骤
+- decision / error path
+- human + agent 协作流程
+
+```bash
+openprd diagram <path> --type product-flow
+```
+
+### 什么时候用 `--input`
+
+如果 Agent 已经基于 Skill 生成了结构化 diagram contract：
+
+```bash
+openprd diagram <path> --type product-flow --input flow-contract.json
+```
+
+这比依赖工具自己推断更稳，也更适合多 Agent 协作。
+
+---
+
+## 四、什么场景可以直接 `freeze`
+
+只有在下面几件事都满足时，才建议 `freeze`：
+
+1. 关键产品字段已经补齐
+2. 用户确认问题已经基本收敛
+3. 如果 diagram gate 生效，对应 diagram 已确认
+4. `openprd next` 不再提示 `clarify-user`
+5. `openprd next` 不再提示 `diagram`
+
+### 典型信号
+
+如果 `openprd next` 显示：
+
+- `Current gate: freeze review`
+
+并且 `Suggested command: openprd freeze .`
+
+这时才适合 freeze。
+
+---
+
+## 五、`status` / `next` 应该怎么看
+
+### `openprd status`
+
+适合回答：
+
+- 我现在处于什么场景？
+- 用户应该参与到什么程度？
+- 当前卡在哪一关？
+- 接下来最可能是哪一关？
+
+重点看这 4 个字段：
+
+- `Scenario`
+- `User participation mode`
+- `Current gate`
+- `Upcoming gate`
+
+例如：
+
+- `Scenario: Cold start (existing project)`
+- `User participation mode: context-plus-confirmation`
+- `Current gate: clarify-user`
+- `Upcoming gate: freeze review`
+
+这说明：
+
+- 项目里已有上下文可以用
+- 但当前仍然要先和用户确认
+- 还没到可以 freeze 的阶段
+
+### `openprd next`
+
+适合回答：
+
+- 下一步最应该做什么？
+- 为什么是这一步？
+- 建议直接执行什么命令？
+- 当前应该问用户哪些问题？
+
+重点看：
+
+- `Next action`
+- `Current gate`
+- `Upcoming gate`
+- `Suggested command`
+- `Suggested questions`
+
+---
+
+## 六、batch capture 怎么用
+
+### 适用场景
+
+Agent 一轮把用户问完之后，最好不要一条条写：
+
+```bash
+openprd capture ... --field ...
+openprd capture ... --field ...
+openprd capture ... --field ...
+```
+
+而是用批量模式。
+
+### 命令
+
+```bash
+openprd capture <path> --json-file answers.json
+```
+
+### 推荐 JSON 格式
+
+```json
+{
+  "problem.problemStatement": {
+    "value": "移动端缺少高效的 Agent 会话与节点管理入口",
+    "source": "user-confirmed"
+  },
+  "users.primaryUsers": {
+    "value": ["运维人员", "Agent 重度用户"],
+    "source": "user-confirmed"
+  },
+  "constraints.dependencies": {
+    "value": ["Auth API", "Node service"],
+    "source": "project-derived"
+  }
+}
+```
+
+### source 的意义
+
+- `user-confirmed`：用户亲口确认
+- `project-derived`：从项目已有材料提取
+- `agent-inferred`：Agent 的推断
+
+最佳实践：
+
+- 产品关键字段优先写成 `user-confirmed`
+- 技术现状、已有系统能力可以写成 `project-derived`
+- 谨慎使用 `agent-inferred`
+
+---
+
+## 七、推荐的最小工作节奏
+
+### 对新项目
+
+```bash
+openprd init <path> --template-pack agent
+openprd status <path>
+openprd clarify <path>
+openprd capture <path> --json-file answers.json
+openprd next <path>
+```
+
+### 对已有项目首次接入 OpenPrd
+
+```bash
+openprd init <path> --template-pack agent
+openprd status <path>
+openprd clarify <path>
+openprd capture <path> --json-file derived-and-confirmed.json
+openprd classify <path> agent
+openprd next <path>
+```
+
+### 对继续推进中的 workspace
+
+```bash
+openprd status <path>
+openprd next <path>
+openprd clarify <path>
+openprd capture <path> --json-file delta-answers.json
+```
+
+---
+
+## 八、团队协作建议
+
+### 给人类看什么
+
+- `openprd status`
+- `openprd next`
+- 当前 diagram artifact
+- open questions
+
+### 给 Agent 什么输入
+
+- repo / docs / README
+- `.openprd/` 当前状态
+- diagram contract
+- 批量 capture 的 answers.json
+
+### 不要做什么
+
+- 不要把 `project-derived` 当成 `user-confirmed`
+- 不要在 `Current gate: clarify-user` 时急着 `synthesize`
+- 不要在 diagram gate 还没过时直接 `freeze`

package/skills/openprd-harness/references/workflow-gates.md

@@ -0,0 +1,51 @@
+# OpenPrd Workflow Gates
+
+## Clarification Gate
+
+Do not synthesize with false confidence. Surface gaps first.
+
+Scenario-aware expectations:
+
+- `cold-start-greenfield`: high user collaboration before structure is locked
+- `cold-start-existing-project`: reuse existing repo context, but still ask the user to confirm the new workspace boundary
+- `continuing-workspace`: ask only targeted delta questions
+
+Examples:
+
+- problem statement still vague
+- primary user unclear
+- success metric missing
+- scope not explicit
+
+## Diagram Gate
+
+Route to diagram review before freeze if:
+
+- architecture still needs confirmation
+- user flow still needs confirmation
+- dependencies or boundaries are important to approval
+- the user explicitly asks for a diagram, flow, or visual explanation
+
+## Freeze Gate
+
+Freeze is appropriate when:
+
+- the synthesized draft exists
+- the user has reviewed the latest critical artifact(s)
+- there are no blockers hidden behind assumptions that should be reviewed first
+
+## Standards Gate
+
+Implementation readiness is appropriate when:
+
+- `openprd standards <path> --verify` passes
+- `docs/basic/` reflects the latest product, flow, structure, and tech-stack facts
+- changed files and folders have had their file manuals and folder README docs checked
+
+## Handoff Gate
+
+Handoff is appropriate when:
+
+- freeze succeeded
+- target system is known
+- the user is ready to move from planning into execution transfer

package/skills/openprd-learning-review/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: openprd-learning-review
+description: 生成并维护 OpenPrd 复盘学习包、题材参考库、证据清单、图文讲解模块、检索/工作示例模块，以及 HTML 电子书阅读器。
+---
+
+# OpenPrd Learning Review
+
+## 何时使用
+
+当用户希望把 OpenPrd 工作区、已完成的 loop 任务，或某个项目领域整理成复盘学习包时，使用这份 skill。典型触发包括：
+
+- 长任务结束，或某个已验证 loop 任务刚完成
+- 用户明确要求复盘某个项目领域或能力面
+- 需要构建或刷新题材模板、证据清单、检索模块或工作示例
+- 需要生成归档在 `.openprd/` 内的 HTML 电子书阅读器
+- 需要把已验证修复或质量复盘连接到可复用的项目经验；此时让 Skill 产物继续经过 `$openprd-quality`，把抽象模式沉淀到 `.openprd/knowledge/skills/`
+- 需要区分“项目经验沉淀”和“操作配置自我成长”；配置缺口、文件识别、命令习惯或用户偏好应进入 `.openprd/growth` 候选，而不是直接写入学习包或共享 Skill
+
+## 核心契约
+
+- 严格分离五层：证据清单、无风格学习内容契约、风格提示词包、带风格学习内容、HTML 阅读器。图文比喻卡和图片提示属于内容契约的一部分，不单独分叉渲染器。
+- 默认模式由配置开启；即使自动模式关闭，手动生成也必须可用。
+- 学习包统一归档到 `.openprd/learning/archive/<packageId>/`。
+- 项目级预防 Skill 单独放在 `.openprd/knowledge/skills/`，不要把复发预防规则只埋在学习电子书里。
+- `.openprd/growth/` 只保存待确认配置、规则和偏好候选；经用户确认后才固化为项目共享配置或 user-local 偏好。
+- 每一条结论都必须能追溯到 source id、路径、摘录和 digest。
+- 除专门的 Markdown 阅读稿外，不要把叙事正文和 provenance 元数据混在同一个文件里。
+
+## 工作流程
+
+1. 从 `.openprd/state/current.json`、`.openprd/state/task-graph.json`、当前 PRD 产物、`docs/basic` 和最近的 loop 报告重建上下文。
+2. 选择主题、题材和可选子风格。默认使用 `internet-product`；对 `xianxia` 默认使用 `cultivation` 提示词包。
+3. 先构建 `evidence-manifest.json`。凡是无法追溯的句子，都标成推断。
+4. 先生成中性的 `learning-content.json`，再加载风格提示词包并运行 Agent-in-the-loop 风格迁移；对产品或非技术读者优先补 `visualExplainer` 图文比喻卡。
+5. 在内容契约里记录提示词包 id、提示词文本、风格迁移报告、图文讲解字段和质量检查结果。
+6. 把 `reader.html` 渲染为固定电子书界面：有书式目录、章节分页、正文独立滚动、进度、上一章/下一章、字体控制、章节级 source 锚点，以及章节内可选的图文比喻卡与图片槽位。不要把单个检索题放进目录。
+7. 把 `learning-package.json`、`learning-content.json`、`learning-content.md`、`evidence-manifest.json` 和 `reader.html` 一起写入归档目录。
+8. 更新 `.openprd/learning/index.json` 和 `.openprd/learning/current.json`，让后续任务能快速找到最新学习包。
+9. 当配置允许自动打开时，在学习包创建后自动打开阅读器。
+10. 如果学习包记录的是已验证修复、重复问题、隐藏调试路径或 Agent 误判，运行或建议运行 `openprd quality <path> --learn --from <eval-report>`，把抽象模式沉淀成未来可触发的项目 Skill。
+
+## 章节结构
+
+每个学习包都尽量覆盖这些模块：
+
+- 解释学习包为何存在的叙事开场
+- 点名相关 `.openprd/` 文件和工作流状态的系统地图章节
+- 帮助产品或非技术读者先建立直觉的图文比喻卡
+- 区分事实、claim 和推断的 provenance 章节
+- 让读者回忆关键机制的检索模块
+- 展示如何迁移到新场景的工作示例模块
+- 告诉读者下一步做什么的收束章节
+
+## 扩展规则
+
+- 新增题材时，扩展题材参考库，不要分叉渲染器。
+- 内容契约必须版本化；当结构变化时，引入新的 schema 版本。
+- 即使文风变化，证据清单中的 source id 和路径也必须保留。
+- 保持 HTML 阅读器稳定，确保历史归档学习包在未来仍可重新打开。
+
+## 参考资料
+
+- `references/prompt-engineering.md`
+- `references/style-packs/xianxia-cultivation.prompt.md`
+- `references/genre-library.md`
+- `references/content-contract.md`
+- `references/evidence-manifest.md`
+- `references/ebook-reader.md`
+- `references/retrieval-worked-example.md`
+- `references/quality-rubric.md`
+
+## 输出期望
+
+最终产物应该像真正可阅读的学习材料，而不是套了浏览器壳的 JSON 导出。内容是主角，阅读器只是稳定的承载框架。
+如果目标读者不是工程师，优先把它做成“先看懂，再深读”的图文短课，而不是技术复盘手册。

package/skills/openprd-learning-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenPrd Learning Review"
+  short_description: "Generate project learning books, visual explainer cards, and genre templates"
+  default_prompt: "Use $openprd-learning-review to design or generate OpenPrd learning-review packages, visual explainer cards, evidence manifests, and HTML ebook-reader artifacts."

package/skills/openprd-learning-review/references/content-contract.md

@@ -0,0 +1,125 @@
+# Learning Content Contract
+
+The contract must stay versioned and renderer-independent.
+
+## Top-Level Fields
+
+- `schema`
+- `version`
+- `packageId`
+- `generatedAt`
+- `title`
+- `topic`
+- `subtitle`
+- `genre`
+- `stylePromptPack`
+- `stylePromptEngineering`
+- `styleTransfer`
+- `trigger`
+- `sourceScope`
+- `audience`
+- `snapshot`
+- `learningGoals`
+- `overviewParagraphs`
+- `outline`
+- `chapters`
+- `evidenceManifestPath`
+- `packagePaths`
+- `related`
+- `nextActions`
+
+## Chapter Shape
+
+Each chapter should support:
+
+- `id`
+- `label`
+- `semanticTitle`
+- `summary`
+- `visualExplainer`
+- `paragraphs`
+- `retrievalBlocks`
+- `workedExamples`
+- `evidenceIds`
+
+## Block Shape
+
+### Retrieval Block
+
+- `prompt`
+- `hint`
+- `answer`
+
+### Worked Example
+
+- `title`
+- `scenario`
+- `steps`
+- `principle`
+
+### Visual Explainer
+
+- `title`
+- `analogy`
+- `scene`
+- `whyItMatters`
+- `takeaways`
+- `image`
+
+### Visual Explainer Image
+
+- `path`
+- `alt`
+- `caption`
+- `prompt`
+
+## Rules
+
+- Facts belong to evidence.
+- Narrative belongs to the contract.
+- Prompt engineering belongs to `stylePromptEngineering`.
+- Style migration audit belongs to `styleTransfer`.
+- Rendering belongs to the HTML reader.
+- The outline should stay chapter-oriented; retrieval questions remain in chapter body content instead of separate TOC leaf nodes.
+- `visualExplainer` helps readers form intuition faster, but it cannot replace evidence or introduce unsupported facts.
+- If `visualExplainer.image.path` is present, prefer a relative path under `packagePaths.assetsDir` so the archived reader stays portable.
+- Claims that cannot be supported by the manifest should be marked as inference.
+- Version the contract whenever the shape changes.
+
+## Minimal Example
+
+```json
+{
+  "schema": "openprd.learning-content.v1",
+  "version": 1,
+  "packageId": "lr-20260512-120000-openprd-review",
+  "title": "《OpenPrd 复盘学习书》",
+  "genre": {
+    "id": "internet-product",
+    "label": "互联网产品"
+  },
+  "chapters": [
+    {
+      "id": "chapter-1",
+      "label": "问题地图",
+      "semanticTitle": "从任务完成回到工作区事实",
+      "summary": "先把发生了什么说清楚。",
+      "visualExplainer": {
+        "title": "像开业前先做联合质检",
+        "analogy": "先别急着开门营业，而是让不同角色独立检查风险。",
+        "scene": "产品负责人先看用户旅程，工程负责人再看实现风险。",
+        "whyItMatters": "非技术读者可以先抓住机制，再回到证据细节。",
+        "takeaways": ["先独立看", "后统一判", "再决定做不做"],
+        "image": {
+          "path": "assets/chapter-1.png",
+          "alt": "开业前联合质检的图文示意",
+          "caption": "图片只帮助理解，不替代证据。"
+        }
+      },
+      "retrievalBlocks": [],
+      "workedExamples": [],
+      "evidenceIds": ["current-state", "task-graph"]
+    }
+  ]
+}
+```

package/skills/openprd-learning-review/references/ebook-reader.md

@@ -0,0 +1,46 @@
+# HTML Ebook Reader
+
+The reader is the fixed output shell. It should be stable enough that archived packages remain readable later.
+
+## Layout
+
+- left: book-like outline with chapter-level navigation and section nodes, but without individual retrieval-question entries
+- center: chapter reader with one chapter shown at a time
+- chapter body may contain an optional `visualExplainer` card with image, analogy, scene, and takeaways
+- no persistent right evidence panel; evidence lives in archive files and chapter-level source anchors
+
+## Required Controls
+
+- previous chapter
+- next chapter
+- font size down
+- font size up
+- progress indicator
+
+## Reader Behavior
+
+- Use chapter paging for next/prev navigation and keep scrolling confined to the chapter body.
+- Highlight the active chapter in the TOC.
+- Keep source anchors available without competing with the text.
+- If a chapter includes a `visualExplainer`, place it near the top of the chapter so non-technical readers can form intuition before reading dense text.
+- Collapse into a single column on narrow screens.
+- Open automatically when the package is created and auto-open is enabled.
+
+## Visual Rules
+
+- Use a calm, paper-like palette.
+- Keep typography readable and avoid over-decorating the page.
+- Visual explainer cards can be stronger in color and layout than the正文, but they must still feel like part of the same reading surface.
+- Do not let side panels compete with the text.
+- Keep all text and controls stable across resize.
+
+## Output Files
+
+- `reader.html`
+- `assets/` (optional generated images for visual explainers)
+- `learning-content.json`
+- `learning-content.md`
+- `evidence-manifest.json`
+- `learning-package.json`
+- `.openprd/learning/index.json`
+- `.openprd/learning/current.json`