@xenonbyte/da-vinci-workflow 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## Unreleased
+
+- No unreleased changes yet.
+
+## v0.1.6 - 2026-03-27
+
+### Added
+- prompt-entry helper routes for `intake`, `prompt`, and `continue` across Codex, Claude, and Gemini
+- `references/prompt-recipes.md` and `docs/prompt-entrypoints.md` to document how those entry routes should be used
+- Chinese companion documents for the repository documentation set
+
+### Changed
+- README, SKILL, workflow examples, mode use cases, and platform adapter documentation now explain when to use prompt-entry helpers
+- installation and asset validation now include the new route files
+- asset validation now covers the full `examples/` and `openspec/` documentation sets, and `openspec/` is now included in the npm package
+
+## v0.1.5 - 2026-03-27
+
+### Fixed
+- `da-vinci status` now validates full installed asset sets for Codex, Claude, and Gemini instead of relying on sentinel files that could miss partial installs
+
+### Changed
+- Claude and Gemini command adapters now use self-contained Da Vinci workflow wording after installation instead of referring to unavailable local skill/reference files
+- README release notes now reflect the current install integrity work and next release priorities
+
+## v0.1.4 - 2026-03-27
+
+### Added
+- redesign-from-code spec partitioning rules for broad UI refreshes
+- redesign-slice guidance for `shared-shell`, `core-pages`, `settings-and-secondary`, `admin-or-restricted`, and `reference-gap-pages`
+
+### Changed
+- `redesign-from-code` now prefers multiple `specs/<slice>/spec.md` files over one oversized `ui-refresh/spec.md` when the refresh spans multiple implementation boundaries
+- `spec checkpoint` now checks whether a redesign spec is too coarse
+- `task checkpoint` now checks whether top-level task groups map cleanly to redesign spec slices
+- `workflow-examples.md` and `mode-use-cases.md` now reflect slice-based spec planning for broad redesign work
+
+### Notes
+- This release keeps `DA-VINCI.md` as the project-level visual contract at the repository root
+- Workflow artifacts remain under `.da-vinci/`, with change-specific artifacts under `.da-vinci/changes/<change-id>/`

package/CHANGELOG.zh-CN.md

@@ -0,0 +1,44 @@
+# 变更日志
+
+> 中文配套文档。若与 `CHANGELOG.md` 存在差异，以英文原文为准。
+
+## Unreleased
+
+- 暂无未发布变更。
+
+## v0.1.6 - 2026-03-27
+
+### 新增
+- 为 Codex、Claude、Gemini 增加了 `intake`、`prompt`、`continue` 三个提示词入口辅助路由
+- 新增 `references/prompt-recipes.md` 和 `docs/prompt-entrypoints.md`，用于说明这些入口路由的使用方式
+- 为仓库文档补充了一套中文配套文档
+
+### 变更
+- README、SKILL、workflow examples、mode use cases、platform adapters 现在都补充了入口辅助路由的使用说明
+- 安装和资产校验已包含新的路由文件
+- 资产校验现在覆盖完整的 `examples/` 和 `openspec/` 文档集合，并且 `openspec/` 也已纳入 npm 包
+
+## v0.1.5 - 2026-03-27
+
+### 修复
+- `da-vinci status` 现在会检查 Codex、Claude、Gemini 的完整安装资产，而不再只依赖少量哨兵文件
+
+### 变更
+- Claude 和 Gemini 安装后的命令文案改成自洽的 Da Vinci 工作流措辞，不再引用未安装的本地 skill/reference 文件
+- README 的发布说明同步更新为当前安装完整性相关工作
+
+## v0.1.4 - 2026-03-27
+
+### 新增
+- 为大范围 UI 刷新增加 `redesign-from-code` 的 spec 拆分规则
+- 为 `shared-shell`、`core-pages`、`settings-and-secondary`、`admin-or-restricted`、`reference-gap-pages` 提供 redesign slice 指导
+
+### 变更
+- 当刷新跨越多个实现边界时，`redesign-from-code` 更倾向于多个 `specs/<slice>/spec.md`，而不是单个巨大的 `ui-refresh/spec.md`
+- `spec checkpoint` 现在会检查 redesign spec 是否过粗
+- `task checkpoint` 现在会检查顶层任务组是否能和 redesign slice 对齐
+- `workflow-examples.md` 和 `mode-use-cases.md` 已同步反映基于 slice 的 spec 规划方式
+
+### 说明
+- `DA-VINCI.md` 仍然作为项目级视觉契约保存在仓库根目录
+- 工作流工件仍然位于 `.da-vinci/` 下，变更级工件位于 `.da-vinci/changes/<change-id>/`

package/README.md

@@ -25,12 +25,15 @@ This workflow is intended for:
 
 ## Current release
 
-Current npm release target:
+Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.5`
+- `@xenonbyte/da-vinci-workflow@0.1.6`
 
 Release highlights:
 
+- prompt-entry helper routes for `intake`, `prompt`, and `continue` are now published across Codex, Claude, and Gemini
+- bilingual repository documentation is now included for the main workflow docs, command references, examples, and OpenSpec change docs
+- asset validation now covers the full `examples/` and `openspec/` documentation sets
 - `da-vinci status` now validates full installed asset sets across Codex, Claude, and Gemini
 - Claude and Gemini command adapters now use self-contained workflow wording after installation
 - Node-first install, uninstall, status, and asset validation commands remain the supported distribution path
@@ -56,6 +59,26 @@ Use when an existing project already has routes, pages, and UI, and the goal is
 
 Use when an existing product needs a scoped requirement change, page addition, or page update.
 
+## Prompt entry helpers
+
+Use these routes when you know you need Da Vinci but do not want to hand-write the first workflow prompt.
+
+- `intake`: choose the correct mode and generate the best executable first prompt
+- `prompt`: generate scenario-specific prompts directly
+- `continue`: inspect existing artifacts and generate the best continuation prompt
+
+Default intent:
+
+- use `intake` for complex existing-project redesigns or whenever the first prompt is hard to phrase
+- use `continue` after `.da-vinci/` artifacts already exist and the workflow needs to resume
+- use `prompt` when the mode is already known and you only want copy-ready prompt text
+
+Route discipline:
+
+- `intake` and `continue` should usually generate a main `$da-vinci ...` or `/da-vinci ...` prompt
+- they should not default the user into `build`
+- `build` remains a direct expert route for workflows that are already implementation-ready
+
 ## Core workflow
 
 Da Vinci runs in this order:
@@ -272,6 +295,14 @@ Preferred:
 $da-vinci <request>
 ```
 
+Entry helpers:
+
+```text
+/prompts:dv-intake
+/prompts:dv-prompt
+/prompts:dv-continue
+```
+
 ### Claude
 
 Preferred:
@@ -280,6 +311,14 @@ Preferred:
 /da-vinci <request>
 ```
 
+Entry helpers:
+
+```text
+/dv:intake
+/dv:prompt
+/dv:continue
+```
+
 ### Gemini
 
 Preferred:
@@ -288,6 +327,14 @@ Preferred:
 /da-vinci <request>
 ```
 
+Entry helpers:
+
+```text
+/dv:intake
+/dv:prompt
+/dv:continue
+```
+
 ## Repo-local forward test
 
 A complete repo-local forward test is available at:
@@ -331,25 +378,56 @@ $da-vinci use redesign-from-code to inventory the existing app, identify current
 $da-vinci use feature-change to add a billing page, generate the relevant Pencil design delta, and create implementation tasks
 ```
 
+### Prompt intake for a complex redesign
+
+```text
+/dv:intake I need to globally replace the UI of an existing Android project. Existing code is the behavior source of truth. HTML references are in /abs/path/to/mockups.
+```
+
+### Continue after inventory and spec work
+
+```text
+/dv:continue Continue this redesign-from-code workflow into full-delivery using the existing Da Vinci artifacts.
+```
+
 ## Workflow examples
 
 See:
 
+- `docs/prompt-entrypoints.md`
 - `docs/workflow-examples.md`
 - `docs/mode-use-cases.md`
 
+## Chinese documentation
+
+Chinese companion documents are included in this repository:
+
+- `README.zh-CN.md`
+- `SKILL.zh-CN.md`
+- `CHANGELOG.zh-CN.md`
+- `docs/zh-CN/`
+- `docs/zh-CN/commands/`
+- `references/zh-CN/`
+- `examples/greenfield-spec-markupflow/*.zh-CN.md`
+- `openspec/changes/da-vinci-v2-1-workflow/*.zh-CN.md`
+
 ## Repository layout
 
 ```text
 da-vinci/
 ├── SKILL.md
+├── SKILL.zh-CN.md
+├── README.zh-CN.md
 ├── agents/
 │   └── openai.yaml
 ├── commands/
 │   ├── claude/
 │   ├── codex/
 │   └── gemini/
+├── docs/
+│   └── zh-CN/
 ├── references/
+│   └── zh-CN/
 └── openspec/
 ```
 

package/README.zh-CN.md

@@ -0,0 +1,293 @@
+# Da Vinci
+
+> 中文配套文档。若与英文原文存在差异，请以 `README.md` 为准。
+
+Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计、页面绑定、实现任务和最终代码的交付工作流。
+
+它遵循一个固定契约：
+
+- requirements 决定 behavior
+- Pencil 决定 presentation
+- code 同时遵循 requirements 和 Pencil
+
+## Da Vinci 适合什么场景
+
+当一个项目需要同时把这三层对齐时，适合使用 Da Vinci：
+
+1. 需求拆解
+2. Pencil 支撑的 UI 设计
+3. 基于需求和设计数据的实现
+
+典型场景：
+
+- 0 到 1 的产品交付
+- 从 brainstorming 走向可实施产品
+- 基于现有代码做全局 UI 重设计
+- 在现有产品上做范围明确的 feature-change
+
+## 当前发布状态
+
+最新已发布 npm 包：
+
+- `@xenonbyte/da-vinci-workflow@0.1.6`
+
+已发布版本重点：
+
+- `intake`、`prompt`、`continue` 三个提示词入口辅助路由已随 Codex、Claude、Gemini 一起发布
+- 主工作流文档、命令说明、示例工件和 OpenSpec 变更文档现在都提供中文配套文档
+- 资产校验现在覆盖完整的 `examples/` 和 `openspec/` 文档集合
+- `da-vinci status` 会校验 Codex、Claude、Gemini 的完整安装资产
+- Claude 和 Gemini 安装后的命令文案已改为自洽的工作流措辞
+- 安装、卸载、状态、资产校验都通过 Node CLI 提供
+- 仓库内含一个 `greenfield-spec` 的本地 forward test
+
+## 支持的工作流模式
+
+Da Vinci V2 支持四种模式：
+
+### `greenfield-spec`
+
+新项目，且需求已经足够清晰，可以直接写 spec。
+
+### `greenfield-brainstorm`
+
+新项目，但输入仍然比较发散，需要先做梳理和收敛。
+
+### `redesign-from-code`
+
+已有项目，代码和行为已存在，目标是做广泛或全局的 UI 重设计。
+
+### `feature-change`
+
+已有项目，只做某个功能、页面、流程的局部修改。
+
+## 提示词入口辅助路由
+
+当你知道自己需要 Da Vinci，但不想自己手写第一条高质量提示词时，可以使用下面三类入口：
+
+- `intake`
+  - 帮你判断该用哪个 mode，并生成最合适的主入口提示词
+- `prompt`
+  - 在场景已知时，直接生成可复制执行的提示词
+- `continue`
+  - 项目里已经有 `.da-vinci/` 工件时，帮你判断如何继续
+
+默认建议：
+
+- 复杂的存量项目重设计，优先用 `intake`
+- 已有工件后继续推进，优先用 `continue`
+- 已经明确知道场景，只缺提示词文本时，用 `prompt`
+
+重要规则：
+
+- `intake` 和 `continue` 通常应该回到主工作流入口，即 `$da-vinci ...` 或 `/da-vinci ...`
+- 它们不应该默认把用户直接导向 `build`
+- `build` 仍然保留，但它是给已经实现就绪的高级直接入口
+
+## 核心工作流顺序
+
+Da Vinci 的默认顺序是：
+
+1. 选择 mode
+2. 生成正确的源工件
+3. 检测或生成 `DA-VINCI.md`
+4. 收集设计输入并登记设计源
+5. 定义或发现页面地图
+6. 创建或更新 Pencil 设计
+7. 绑定实现页面到 Pencil 页面
+8. 通过 MCP 读取 Pencil 设计数据
+9. 生成实现任务
+10. 根据 requirements 和 Pencil 数据实现代码
+11. 校验需求漂移和设计漂移
+
+## 默认工件
+
+根据不同 mode，工作流可能使用这些工件：
+
+- `.da-vinci/changes/<change-id>/brainstorm.md`
+- `.da-vinci/project-inventory.md`
+- `DA-VINCI.md`
+- `.da-vinci/changes/<change-id>/design-brief.md`
+- `.da-vinci/design-registry.md`
+- `.da-vinci/page-map.md`
+- `.da-vinci/changes/<change-id>/proposal.md`
+- `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
+- `.da-vinci/changes/<change-id>/design.md`
+- `.da-vinci/changes/<change-id>/pencil-design.md`
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`
+- `.da-vinci/changes/<change-id>/tasks.md`
+- `.da-vinci/changes/<change-id>/verification.md`
+
+工件含义：
+
+- `brainstorm.md`：需求尚未稳定前的原始想法整理
+- `project-inventory.md`：现有代码库里的路由、页面、UI 结构盘点
+- `DA-VINCI.md`：项目级视觉契约
+- `design-brief.md`：设计方向、形态、密度、品牌和限制条件
+- `design-registry.md`：项目级 `.pen` 设计源登记
+- `page-map.md`：页面、职责、状态和共享区域
+- `proposal.md`：范围、目标、非目标和成功标准
+- `spec.md`：行为、状态、边界和验收规则
+- `design.md`：信息架构、页面结构和交互策略
+- `pencil-design.md`：Pencil 页面、屏幕、注释和说明
+- `pencil-bindings.md`：实现页面和 Pencil 页面之间的映射
+- `tasks.md`：任务分组和实施顺序
+- `verification.md`：覆盖度和漂移检查
+
+## 安装
+
+安装 npm 包：
+
+```bash
+npm install -g @xenonbyte/da-vinci-workflow
+```
+
+安装平台资产：
+
+```bash
+da-vinci install --platform codex,claude,gemini
+```
+
+常用命令：
+
+```bash
+da-vinci status
+da-vinci validate-assets
+da-vinci uninstall --platform codex,claude,gemini
+```
+
+安装目标：
+
+- Codex prompts：`~/.codex/prompts/`
+- Codex skill：`~/.codex/skills/da-vinci/`
+- Claude commands：`~/.claude/commands/`
+- Gemini commands：`~/.gemini/commands/`
+
+## 平台使用方式
+
+### Codex
+
+主入口：
+
+```text
+$da-vinci <request>
+```
+
+辅助入口：
+
+```text
+/prompts:dv-intake
+/prompts:dv-prompt
+/prompts:dv-continue
+```
+
+### Claude
+
+主入口：
+
+```text
+/da-vinci <request>
+```
+
+辅助入口：
+
+```text
+/dv:intake
+/dv:prompt
+/dv:continue
+```
+
+### Gemini
+
+主入口：
+
+```text
+/da-vinci <request>
+```
+
+辅助入口：
+
+```text
+/dv:intake
+/dv:prompt
+/dv:continue
+```
+
+## 示例请求
+
+### Greenfield spec
+
+```text
+$da-vinci use greenfield-spec to break down a new desktop software project for annotated design delivery
+```
+
+### Brainstorm synthesis
+
+```text
+$da-vinci use greenfield-brainstorm to turn several product ideas into a page map, Pencil design plan, and implementation tasks
+```
+
+### Redesign from code
+
+```text
+$da-vinci use redesign-from-code to inventory the existing app, identify current pages, and generate a new Pencil-backed UI plan
+```
+
+### Feature change
+
+```text
+$da-vinci use feature-change to add a billing page, generate the relevant Pencil design delta, and create implementation tasks
+```
+
+### 复杂重设计先做 intake
+
+```text
+/dv:intake I need to globally replace the UI of an existing Android project. Existing code is the behavior source of truth. HTML references are in /abs/path/to/mockups.
+```
+
+### 已有工件后继续推进
+
+```text
+/dv:continue Continue this redesign-from-code workflow into full-delivery using the existing Da Vinci artifacts.
+```
+
+## 文档导航
+
+英文文档：
+
+- `docs/prompt-entrypoints.md`
+- `docs/workflow-examples.md`
+- `docs/mode-use-cases.md`
+- `references/`
+
+中文文档：
+
+- `README.zh-CN.md`
+- `SKILL.zh-CN.md`
+- `CHANGELOG.zh-CN.md`
+- `docs/zh-CN/`
+- `docs/zh-CN/commands/`
+- `references/zh-CN/`
+- `examples/greenfield-spec-markupflow/*.zh-CN.md`
+- `openspec/changes/da-vinci-v2-1-workflow/*.zh-CN.md`
+
+## 仓库布局
+
+```text
+da-vinci/
+├── SKILL.md
+├── SKILL.zh-CN.md
+├── README.md
+├── README.zh-CN.md
+├── agents/
+│   └── openai.yaml
+├── commands/
+│   ├── claude/
+│   ├── codex/
+│   └── gemini/
+├── docs/
+│   └── zh-CN/
+├── references/
+│   └── zh-CN/
+└── openspec/
+```

package/SKILL.md

@@ -80,7 +80,40 @@ Canonical workflow name is `da-vinci`.
 
 - Codex preferred: `$da-vinci <request>`
 - Claude and Gemini preferred: `/da-vinci <request>` when platform adapters exist
-- Explicit action routes may exist later, but natural-language invocation is the default path
+- Explicit action routes also exist for workflow entry help:
+  - Codex: `/prompts:dv-intake`, `/prompts:dv-prompt`, `/prompts:dv-continue`
+  - Claude and Gemini: `/dv:intake`, `/dv:prompt`, `/dv:continue`
+- Natural-language invocation remains the default path
+
+## Prompt Entry Routes
+
+Use these helper actions when the user needs help entering or resuming the workflow:
+
+1. `intake`
+   - use when the user describes a project situation but does not know how to phrase the best Da Vinci request
+   - output:
+     - recommended mode
+     - recommended delivery intent
+     - one primary executable workflow prompt
+     - one more conservative prompt when useful
+     - one continuation prompt when the workflow is likely to pause
+     - missing inputs that would materially change the result
+   - `intake` should usually generate a main workflow prompt, not a `build`-only prompt
+
+2. `prompt`
+   - use when the user explicitly asks for a prompt template or scenario-specific prompt
+   - generate one or more copy-ready prompts aligned to the stated scenario
+   - keep prompts operational, not generic advice
+
+3. `continue`
+   - use when workflow artifacts already exist and the user needs to resume
+   - inspect the current artifacts first
+   - output:
+     - detected workflow state
+     - gaps or blockers
+     - one executable continuation prompt
+   - do not restart discovery if the artifacts already provide enough truth
+   - do not default to `build` unless the project is clearly implementation-ready
 
 ## V2 Mode Selection
 
@@ -177,6 +210,7 @@ Load only the reference that matches the current step:
 - Read `references/page-mapping.md` when defining project pages, Pencil pages, and route-to-screen bindings
 - Read `references/pencil-design-to-code.md` when turning Pencil data into implementation
 - Read `references/platform-adapters.md` when guiding users on Codex, Claude, or Gemini invocation patterns
+- Read `references/prompt-recipes.md` when generating intake, prompt, or continue helper outputs
 
 ## Default Artifacts