@openprd/cli 0.1.8 → 0.1.10

package/README.md

@@ -39,7 +39,7 @@ OpenPrd 是一个轻量但结构化的 **PRD harness**。你只需要先把问
 
 ![OpenPrd 需求分流节奏](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-requirement-routing-zh.png)
 
-- **快速修正**：问题已经很明确，影响小，验收也清楚。通常直接处理，改完告诉你改了什么、怎么验证。
+- **直接处理**：问题已经很明确，影响小，验收也清楚。通常直接处理，改完告诉你改了什么、怎么验证。
 - **现有功能优化**：目标明确，但会牵动几个页面、状态或用户动作。OpenPrd 会先用人话给你一版 mini-plan，方向对了再继续。
 - **新功能 / 新流程方案**：范围更大，角色更多，或者业务风险还不清楚。先把用户场景、第一版、先不做什么和主要风险讲清楚，再进入完整方案和任务拆解。
 
@@ -125,12 +125,27 @@ OpenPrd 会沿着两条看得见的循环，越用越贴合你们的协作方式
 - 下次会自动带上什么：先问什么、先看什么、交付前先收什么材料。
 - 为什么有用：团队不用每次重新解释“这类项目该怎么开场”，而是直接从更合适的默认方式开始。
 
+## 默认带上的增强能力
+
+OpenPrd 不只是帮你把协作流程说清楚，也会把“该去哪里找资料、先看什么再继续”这件事提前铺好。对公开仓库、第三方技术文档和图标素材，它会默认走更合适的增强路径，而不是等你每次手动提醒。
+
+![OpenPrd 默认增强能力](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-best-practices-zh.png)
+
+- **公开仓库 / 对标参考**：优先用 `DeepWiki` 更快看懂架构、关键流程和实现线索。
+- **第三方库 / CLI / SDK / MCP**：优先用 `Context7` 看最新文档、配置方式、版本差异和迁移说明。
+- **图标与视觉素材**：按用途分流到更合适的资源站或实现库，不把 UI 图标、AI 品牌、技术栈图标和 3D 素材混着找。
+- **项目自己的做法优先**：先看仓库里已经确认过的经验和约定，再补外部最佳实践，不让通用建议盖过项目语境。
+
+这些增强能力默认是“配上更好”，不是硬依赖。没配置也不会影响初始化或当前任务，只会在后续建议里提醒你补上。
+
 ## 功能
 
 - **Clarification-first**：`clarify -> capture -> classify -> interview -> synthesize -> diagram -> freeze -> handoff`
 - **场景感知协同**：区分空项目冷启动、已有项目首次接入、持续推进中的 workspace
 - **自我成长机制**：把真实项目里确认过的做法沉淀成可复用的 `项目级 Skill`，并按场景沉淀 `动态参数配置`
 - **来源感知采集**：支持 `user-confirmed` / `project-derived` / `agent-inferred` / `agent-normalized`
+- **最佳实践路由**：在公开仓库理解、第三方技术文档、图标资源和协作方式优化这类任务里，先把请求路由到更合适的证据源
+- **项目级 benchmark registry**：支持 `benchmark add / observe / approve / verify`，把被反复采纳的外部来源沉淀成项目自己的长期参考
 - **图形评审工件**：支持 `architecture` 和 `product-flow`
 - **界面视觉对比工件**：把效果图与实现截图合成左右对比 JPG，用于阶段性复刻评审
 - **Contract 驱动图渲染**：支持从 JSON contract 显式渲染
@@ -196,7 +211,7 @@ openprd init /path/to/project --template-pack agent
 npx @openprd/cli@latest init /path/to/project --template-pack agent
 ```
 
-`init` 会创建 `.openprd/`、`docs/basic/`、`AGENTS.md`，并生成 Codex / Claude / Cursor 三端引导。Codex 项目会同时写入 `.codex/config.toml`、`.codex/hooks.json`、`.codex/hooks/openprd-hook.mjs`，并开启用户级 Codex `codex_hooks = true`。
+`init` 会创建 `.openprd/`、`docs/basic/`、`AGENTS.md`，并生成 Codex / Claude / Cursor 三端引导。Codex 项目会同时写入 `.codex/config.toml`、`.codex/hooks.json`、`.codex/hooks/openprd-hook.mjs`，并开启用户级 Codex `hooks = true`。
 
 Codex hooks 默认使用 `lite` 模式：安装 `UserPromptSubmit`、轻量
 `PreToolUse` 写入门禁，以及轻量 `Stop` 收工回顾。明确提到 OpenPrd、PRD、深度调研、深度对标、复刻、
@@ -248,7 +263,7 @@ openprd clarify /path/to/project
 
 OpenPrd 会先按用户可见的需求类型接住这句话，而不是先让你填一堆表单：
 
-- **快速修正**：通常直接做，做完告诉你改了什么、怎么验。
+- **直接处理**：通常直接做，做完告诉你改了什么、怎么验。
 - **现有功能优化**：先给一版 mini-plan，你确认方向后再继续。
 - **新功能 / 新流程方案**：先把场景、范围、第一版和风险说清楚，再进入 `review`、`change` 和 `tasks`。
 
@@ -542,7 +557,7 @@ openprd loop /path/to/project --run --agent codex --dry-run
 
 - `AGENTS.md` 中的 OpenPrd 管理规则
 - `.codex/skills/`、`.codex/prompts/`、`.codex/config.toml`、`.codex/hooks.json` 和 `.codex/hooks/openprd-hook.mjs`
-- 用户级 Codex config 的 `features.codex_hooks = true`
+- 用户级 Codex config 的 `features.hooks = true`
 - `.claude/skills/`、`.claude/commands/openprd/` 和 `CLAUDE.md`
 - `.cursor/rules/openprd.mdc` 和 `.cursor/commands/`
 - `.openprd/harness/install-manifest.json`、`hook-state.json`、`events.jsonl`、`drift-report.json` 和 `visual-reviews/`
@@ -571,7 +586,7 @@ PreToolUse 写入门禁，并把匹配范围限制在直接编辑工具上，同
 Codex 或 Claude 会话只处理这一个任务。每个任务完成后必须先自测，失败就修复并
 重新自测；前端界面任务在 Codex 客户端优先用 Computer Use，在 Codex CLI 和
 Claude Code 中优先用 Playwright、MCP 浏览器自动化或项目已有 e2e 工具。验证
-通过后，`loop --finish` 会写入阶段性测试报告，并可为该任务生成独立 commit。
+通过后，`loop --finish` 会写入阶段性测试报告，并可在隔离 worktree 中为该任务生成独立 commit。
 界面任务完成前必须运行 `openprd visual-compare`：已有参考图时截实现图并走
 `--reference/--actual`，没有参考图但改动界面时先留修改前截图、完成后留修改后截图并走
 `--before/--after`，查看左右对比 JPG 后才能完成任务。
@@ -592,12 +607,15 @@ openprd loop . --plan --change <change-id>
 openprd loop . --next
 openprd loop . --prompt --agent codex
 openprd loop . --run --agent codex --dry-run
+openprd loop . --run --agent codex --worktree ../openprd-loop-wt --branch loop/feature-x --dry-run
 openprd loop . --run --agent claude --dry-run
 openprd loop . --verify --item T001.01
-openprd loop . --finish --item T001.01 --commit --message "新增版本说明入口"
+openprd loop . --finish --item T001.01 --worktree ../openprd-loop-wt --branch loop/feature-x --commit --message "新增版本说明入口"
 ```
 
-如果项目启用了 `release` 版本轨道，`loop --finish --commit` 会在成功提交后把当前任务的短文案累计到当前项目版本下，并尝试把同名本地 tag（例如 `0.1.23`）移动到最新 commit。若远端已存在同名 tag，OpenPrd 会提示风险并跳过本地 tag 改写，不会静默覆盖远端历史。
+如果项目启用了 `release` 版本轨道，`loop --finish --commit` 会在成功提交时把当前任务的短文案累计到当前项目版本下，并尝试把同名本地 tag（例如 `0.1.23`）移动到最新 commit。若远端已存在同名 tag，OpenPrd 会提示风险并跳过本地 tag 改写，不会静默覆盖远端历史。
+
+主工作区已经有未纳入本任务提交的改动时，`loop --finish --commit` 默认会阻断，提示你改用 `--worktree <path> --branch <name>`；只有你明确知道要在主工作区做 scoped commit 时，才显式加 `--allow-dirty-main`。提交范围也不再是 `git add -A`，而是按任务 `write-scope`、任务来源文件和本轮新增 touched files 收窄，避免把无关改动卷进单任务 commit。
 
 Loop 状态会沉淀在 `.openprd/harness/`：
 
@@ -605,11 +623,11 @@ Loop 状态会沉淀在 `.openprd/harness/`：
 - `feature-list.json`：每个任务都会带一个人类可读的 `taskHandle`，例如
   `change-id:T001.01:task-title`，方便跨对话继续同一任务，而不是只靠聊天 UUID
 - `progress.md`：给人看的进度记录
-- `agent-sessions.jsonl`：每次 prompt / run / finish 的结构化事件，也会记录任务句柄和任务标题
+- `agent-sessions.jsonl`：每次 prompt / run / finish 的结构化事件，也会记录任务句柄、任务标题、worktree 路径、分支和 commit sha
 - `bootstrap.sh`：每个新会话启动时执行的检查脚本
-- `loop-state.json`：当前任务 id、任务句柄、任务标题，以及最近一次 Agent 会话状态
+- `loop-state.json`：当前任务 id、任务句柄、任务标题、baseline 脏文件，以及最近一次 worktree / 分支 / commit 状态
 - `loop-prompts/`：生成过的单任务提示词，便于审计和复用
-- `test-reports/`：每个任务的阶段性测试报告，会和任务改动一起提交
+- `test-reports/`：每个任务的阶段性测试报告，供审查、回归和后续会话复用
 
 建议先用 `--dry-run`，让 OpenPrd 生成提示词和准确执行命令，但不直接启动 Agent。
 `--agent codex` / `--agent claude` 会使用默认 CLI 集成；只有需要接入团队自定义

package/README_EN.md

@@ -64,6 +64,24 @@ OpenPrd is strongest when the hard part is not just "what code should be written
 but "what should people confirm, what should stay visible, and what evidence is
 enough to move forward."
 
+## Built-In Best-Practice Routing And Default Enhancers
+
+OpenPrd does more than sequence requirement work. It also ships with a best-practice routing layer so the agent can look in the right place before it changes design, copy, or code.
+
+- **Public-repo architecture understanding**: when the task is to understand a public GitHub repository, its subsystem layout, or a key execution flow, OpenPrd pushes the agent toward `DeepWiki` first
+- **Third-party technical documentation**: when the task depends on library, framework, API, CLI, or MCP usage, config, limits, version differences, or migration paths, OpenPrd pushes the agent toward `Context7` first
+- **Icons and visual assets**: when the task is to choose UI icons, AI brand icons, tech-stack icons, 3D assets, or functional icon resources, OpenPrd routes that request toward more appropriate sources instead of making the agent guess on the fly
+- **Project-level long-term references**: repeatedly adopted external sources can be promoted into the project's own reusable best-practice registry
+
+The goal is not to pile up links. The goal is to make "where should we look first, why this source, and when is the evidence sufficient" part of the normal collaboration flow. For AI coding work, that directly affects design quality, technical judgment, and implementation stability.
+
+Common built-in enhancement directions include:
+
+- `DeepWiki`: understand public GitHub repository architecture, module relationships, and key flows
+- `Context7`: retrieve current third-party technical docs, config guidance, version differences, and migration notes
+- Icon and visual-asset routing: prefer sources such as `Phosphor Icons`, `LobeHub Icons`, `Tech Icons`, `Thiings`, and `iconfont` by use case
+- Icon implementation library suggestions: when the work reaches frontend code, narrow to `Lucide`, `Tabler`, or `React Icons` based on project fit
+
 ## Common Real-World Scenarios
 
 Recent Codex project usage kept clustering around the same kinds of work: fuzzy
@@ -150,6 +168,8 @@ automatically.
 - **Scenario-aware collaboration**: distinguish greenfield cold start, existing-project cold start, and continuing workspaces
 - **Self-evolving collaboration**: turn confirmed project habits into reusable `Project-Level Skill`s and adapt `Dynamic Parameter Config` by scenario
 - **Source-aware capture**: mark inputs as `user-confirmed`, `project-derived`, `agent-inferred`, or `agent-normalized`
+- **Best-practice routing**: route public-repo understanding, third-party technical docs, icon resources, and workflow optimization requests to stronger evidence sources before implementation
+- **Project-level benchmark registry**: support `benchmark add / observe / approve / verify` so repeatedly adopted external sources can become durable project references
 - **Diagram review artifacts**: generate both architecture and product-flow diagrams
 - **UI visual comparison artifacts**: combine reference images and implementation screenshots into side-by-side JPG reviews for visual replication work
 - **Contract-driven diagrams**: render from validated JSON contracts
@@ -161,7 +181,7 @@ automatically.
 - **Project knowledge skills**: turn verified fixes and recurring diagnosis patterns into reusable `.openprd/knowledge/skills/` experience skills
 - **OpenPrd change and task execution**: materialize PRD snapshots into change files, validate them, apply accepted specs, archive changes, and advance structured tasks by dependency order
 - **Long-running agent loop**: turn accepted change tasks into one-task-per-session Codex or Claude execution prompts with verification, progress logs, and optional task commits
-- **Default agent integration**: generate Codex, Claude, and Cursor guidance from one OpenPrd source, including Codex hooks with `codex_hooks = true`
+- **Default agent integration**: generate Codex, Claude, and Cursor guidance from one OpenPrd source, including Codex hooks with `hooks = true`
 - **Agent harness skills**: repo-local skills for shared rules, workflow control, and diagram review
 
 ## Tech Stack
@@ -229,7 +249,7 @@ If `openprd` is not on `PATH` yet, run the same init command through `npx`:
 npx @openprd/cli@latest init /path/to/project --template-pack agent
 ```
 
-`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 `codex_hooks = true`.
+`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`.
 
 Codex hooks default to `lite`: `UserPromptSubmit`, a lightweight `PreToolUse`
 write gate, and a lightweight `Stop` end-of-turn review. Context is injected for prompts that explicitly mention OpenPrd,
@@ -619,7 +639,7 @@ or `openprd setup` inside a project.
 
 - `AGENTS.md` managed OpenPrd rules
 - `.codex/skills/`, `.codex/prompts/`, `.codex/config.toml`, `.codex/hooks.json`, and `.codex/hooks/openprd-hook.mjs`
-- user-level Codex config with `features.codex_hooks = true`
+- user-level Codex config with `features.hooks = true`
 - `.claude/skills/`, `.claude/commands/openprd/`, and `CLAUDE.md`
 - `.cursor/rules/openprd.mdc` and `.cursor/commands/`
 - `.openprd/harness/install-manifest.json`, `hook-state.json`, `events.jsonl`, `drift-report.json`, and `visual-reviews/`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openprd/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "AI-native PRD workspace and lifecycle CLI",
   "type": "module",
   "license": "MIT",
@@ -14,14 +14,35 @@
     "README_EN.md",
     "SECURITY.md",
     "bin",
-    "docs/assets",
     "scripts",
     "src",
     ".openprd",
     "!.openprd/artifacts",
     "!.openprd/artifacts/**",
+    "!.openprd/benchmarks/evidence",
+    "!.openprd/benchmarks/evidence/**",
+    "!.openprd/benchmarks/inbox",
+    "!.openprd/benchmarks/inbox/**",
+    "!.openprd/discovery",
+    "!.openprd/discovery/**",
+    "!.openprd/engagements/active/architecture-diagram.html",
+    "!.openprd/engagements/active/architecture-diagram.json",
+    "!.openprd/engagements/active/architecture-diagram.mmd",
+    "!.openprd/engagements/active/brainstorm.html",
+    "!.openprd/engagements/active/brainstorm.json",
     "!.openprd/harness",
     "!.openprd/harness/**",
+    "!.openprd/engagements/active/flows.md",
+    "!.openprd/engagements/active/handoff.md",
+    "!.openprd/engagements/active/product-flow-diagram.html",
+    "!.openprd/engagements/active/product-flow-diagram.json",
+    "!.openprd/engagements/active/product-flow-diagram.mmd",
+    "!.openprd/engagements/active/review.html",
+    "!.openprd/engagements/active/roles.md",
+    "!.openprd/engagements/work-units",
+    "!.openprd/engagements/work-units/**",
+    "!.openprd/exports",
+    "!.openprd/exports/**",
     "!.openprd/learning",
     "!.openprd/learning/**",
     "!.openprd/quality/evidence",
@@ -37,8 +58,26 @@
     "!.openprd/knowledge/patterns/**",
     "!.openprd/knowledge/skills",
     "!.openprd/knowledge/skills/**",
+    "!.openprd/knowledge/adoption.jsonl",
+    "!.openprd/knowledge/candidates",
+    "!.openprd/knowledge/candidates/**",
+    "!.openprd/knowledge/drafts",
+    "!.openprd/knowledge/drafts/**",
+    "!.openprd/knowledge/index.json",
+    "!.openprd/knowledge/review-signals.jsonl",
+    "!.openprd/reviews",
+    "!.openprd/reviews/**",
+    "!.openprd/sessions",
+    "!.openprd/sessions/**",
+    "!.openprd/state/changes.json",
+    "!.openprd/state/current.json",
     "!.openprd/state/events.jsonl",
+    "!.openprd/state/freeze.json",
+    "!.openprd/state/release-ledger.json",
     "!.openprd/state/task-graph.json",
+    "!.openprd/state/version-index.json",
+    "!.openprd/state/versions",
+    "!.openprd/state/versions/**",
     "!.openprd/engagements/active/decision-log.md",
     "!.openprd/engagements/active/open-questions.md",
     "!.openprd/engagements/active/progress.md",