@xenonbyte/da-vinci-workflow 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## Unreleased
+
+- No unreleased changes yet.
+
+## v0.1.7 - 2026-03-27
+
+### Changed
+- Chinese companion docs are now intentionally limited to `README.zh-CN.md` and `docs/zh-CN/`
+- `.npmrc` and `openspec/` are now local-only and no longer tracked or shipped in the npm package
+- asset validation now checks only shipped repository assets
+
+### Removed
+- Chinese mirror docs for commands, references, examples, and changelog
+- OpenSpec planning artifacts from version control and npm packaging
+
+## 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/README.md

@@ -25,14 +25,18 @@ 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.7`
 
 Release highlights:
 
+- prompt-entry helper routes for `intake`, `prompt`, and `continue` are now published across Codex, Claude, and Gemini
+- Chinese companion docs are now intentionally limited to `README.zh-CN.md` and `docs/zh-CN/`
+- asset validation now covers the full shipped documentation set
 - `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
+- `.npmrc` and `openspec/` are kept local-only and are no longer versioned or shipped in the npm package
 - Node-first install, uninstall, status, and asset validation commands remain the supported distribution path
 - repo-local forward-test example for a `greenfield-spec` workflow remains included
 
@@ -56,6 +60,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 +296,14 @@ Preferred:
 $da-vinci <request>
 ```
 
+Entry helpers:
+
+```text
+/prompts:dv-intake
+/prompts:dv-prompt
+/prompts:dv-continue
+```
+
 ### Claude
 
 Preferred:
@@ -280,6 +312,14 @@ Preferred:
 /da-vinci <request>
 ```
 
+Entry helpers:
+
+```text
+/dv:intake
+/dv:prompt
+/dv:continue
+```
+
 ### Gemini
 
 Preferred:
@@ -288,6 +328,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,26 +379,48 @@ $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`
+- `docs/zh-CN/`
+
 ## Repository layout
 
 ```text
 da-vinci/
 ├── SKILL.md
+├── README.zh-CN.md
 ├── agents/
 │   └── openai.yaml
 ├── commands/
 │   ├── claude/
 │   ├── codex/
 │   └── gemini/
-├── references/
-└── openspec/
+├── docs/
+│   └── zh-CN/
+└── references/
 ```
 
 ## Current status
@@ -360,7 +430,6 @@ The repository currently contains:
 - the Da Vinci skill
 - three-platform command adapters
 - workflow references
-- OpenSpec planning artifacts for the skill itself
 - workflow examples
 
 Next natural work for the repository:

package/README.zh-CN.md

@@ -0,0 +1,285 @@
+# 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.7`
+
+已发布版本重点：
+
+- `intake`、`prompt`、`continue` 三个提示词入口辅助路由已随 Codex、Claude、Gemini 一起发布
+- 中文配套文档现在刻意只保留 `README.zh-CN.md` 和 `docs/zh-CN/`
+- 资产校验现在覆盖完整的随包文档集合
+- `da-vinci status` 会校验 Codex、Claude、Gemini 的完整安装资产
+- Claude 和 Gemini 安装后的命令文案已改为自洽的工作流措辞
+- `.npmrc` 和 `openspec/` 现在只本地保留，不再进入版本管理和 npm 包
+- 安装、卸载、状态、资产校验都通过 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`
+- `docs/zh-CN/`
+
+## 仓库布局
+
+```text
+da-vinci/
+├── SKILL.md
+├── README.md
+├── README.zh-CN.md
+├── agents/
+│   └── openai.yaml
+├── commands/
+│   ├── claude/
+│   ├── codex/
+│   └── gemini/
+├── docs/
+│   └── zh-CN/
+└── references/
+```

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
 

package/commands/claude/da-vinci.md

@@ -9,6 +9,9 @@ Platform: Claude
 Default workflow entry: `/da-vinci <request>`
 
 Available routes:
+- `/dv:intake` - Turn a rough project situation into the best executable Da Vinci entry prompt.
+- `/dv:prompt` - Generate scenario-specific Da Vinci prompts when the user wants prompt text directly.
+- `/dv:continue` - Generate the best continuation prompt from existing Da Vinci artifacts.
 - `/dv:breakdown` - Break a product or page request into scope, flows, states, and requirements.
 - `/dv:design` - Plan or create Pencil-backed page designs from approved requirements.
 - `/dv:tasks` - Generate implementation tasks from requirements plus Pencil design coverage.
@@ -19,4 +22,6 @@ Notes:
 - Requirements decide behavior.
 - Pencil decides presentation.
 - Code must follow both.
+- Use `intake` when the user needs help phrasing the first workflow request.
+- Use `continue` when `.da-vinci/` artifacts already exist and the workflow must resume.
 - Keep workflow semantics shared across Codex, Claude, and Gemini.

package/commands/claude/dv/continue.md

@@ -0,0 +1,24 @@
+---
+description: Generate the best continuation prompt from existing Da Vinci artifacts.
+---
+# Da Vinci Continue
+
+Use the Da Vinci workflow for this request.
+
+Action: `continue`
+
+Focus on:
+- inspect existing workflow artifacts first
+- detect the current workflow phase
+- generate the best executable continuation prompt
+
+Output should include:
+- detected workflow state
+- missing or weak artifacts
+- one primary `/da-vinci continue ...` prompt
+- one more conservative continuation prompt when useful
+
+Route discipline:
+- do not restart discovery if the current artifacts already contain enough truth
+- do not default the user into `/dv:build` unless the project is clearly implementation-ready
+- continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine

package/commands/claude/dv/intake.md

@@ -0,0 +1,26 @@
+---
+description: Turn a rough project situation into the best executable Da Vinci entry prompt.
+---
+# Da Vinci Intake
+
+Use the Da Vinci workflow for this request.
+
+Action: `intake`
+
+Focus on:
+- understand the project starting point
+- choose the correct workflow mode
+- identify behavior truth, design truth, and delivery intent
+- generate the best executable Da Vinci prompt for the next step
+
+Output should include:
+- recommended mode
+- recommended delivery intent
+- one primary executable `/da-vinci ...` prompt
+- one more conservative prompt when useful
+- one follow-up `/da-vinci continue ...` prompt when the workflow is likely to pause
+- missing inputs that would materially change the result
+
+Route discipline:
+- do not default the user into `/dv:build`
+- `intake` should usually produce a main workflow prompt, not a build-only prompt

package/commands/claude/dv/prompt.md

@@ -0,0 +1,24 @@
+---
+description: Generate scenario-specific Da Vinci prompts for a known workflow need.
+---
+# Da Vinci Prompt
+
+Use the Da Vinci workflow for this request.
+
+Action: `prompt`
+
+Focus on:
+- generate copy-ready prompts for a known scenario
+- keep the prompt operational and specific to the stated project reality
+
+Output should include:
+- one primary executable prompt
+- one more conservative prompt when useful
+- one continuation prompt when the scenario is likely to need a later resume step
+
+Prompt quality rules:
+- state behavior truth
+- state design reference truth
+- state delivery intent
+- state conflict handling rules
+- make state, subpage, dialog, and overlay coverage explicit when complexity is high

package/commands/codex/prompts/da-vinci.md

@@ -10,6 +10,9 @@ Codex usage model:
 - Explicit routing: `/prompts:da-vinci` and `/prompts:dv-*`
 
 Available routes:
+- `/prompts:dv-intake` - Turn a rough project situation into the best executable Da Vinci entry prompt.
+- `/prompts:dv-prompt` - Generate scenario-specific Da Vinci prompts when the user wants prompt text directly.
+- `/prompts:dv-continue` - Generate the best continuation prompt from existing Da Vinci artifacts.
 - `/prompts:dv-breakdown` - Break a request into requirements, pages, flows, and states.
 - `/prompts:dv-design` - Plan or create Pencil-backed designs from approved requirements.
 - `/prompts:dv-tasks` - Generate implementation tasks from requirements plus Pencil.
@@ -18,6 +21,8 @@ Available routes:
 
 Important:
 - Treat `/prompts:*` as action selectors in Codex.
+- Use `intake` when the user does not know how to phrase the first request.
+- Use `continue` when `.da-vinci/` artifacts already exist and the workflow must resume.
 - If details are still needed after route selection, provide them in the next message.
 - Requirements decide behavior.
 - Pencil decides presentation.

package/commands/codex/prompts/dv-continue.md

@@ -0,0 +1,24 @@
+---
+description: Da Vinci continuation route for Codex.
+---
+# Da Vinci Continue
+
+Use the `da-vinci` skill for this request.
+
+Action: `continue`
+
+Goal:
+- inspect existing workflow artifacts first
+- detect the current workflow phase
+- generate the best executable continuation prompt
+
+Output should include:
+- detected workflow state
+- missing or weak artifacts
+- one primary `$da-vinci continue ...` prompt
+- one more conservative continuation prompt when useful
+
+Route discipline:
+- do not restart discovery if the current artifacts already contain enough truth
+- do not default the user into `/prompts:dv-build` unless the project is clearly implementation-ready
+- continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine