@xenonbyte/da-vinci-workflow 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,27 @@
 
 - No unreleased changes yet.
 
+## v0.1.8 - 2026-03-27
+
+### Added
+- Codex natural-language usage guides in `docs/codex-natural-language-usage.md` and `docs/zh-CN/codex-natural-language-usage.md`
+
+### Changed
+- Codex workflow docs now standardize on `$da-vinci ...` natural-language entry patterns for `intake`, `prompt`, `continue`, and direct mode usage
+- Da Vinci now documents `.da-vinci/designs/` as the default project-local location for persisted Pencil `.pen` files
+- artifact templates, mode guides, and design references now record preferred project-local `.pen` paths in `design-registry.md`
+
+## 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

package/README.md

@@ -27,15 +27,19 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.6`
+- `@xenonbyte/da-vinci-workflow@0.1.8`
 
 Release highlights:
 
+- Codex natural-language usage is now documented explicitly, including `intake`, `prompt`, `continue`, and direct mode entry patterns
+- project-local Pencil `.pen` files are now documented to persist under `.da-vinci/designs/`
+- design registry and artifact templates now record preferred persisted `.pen` paths for project-local reuse
 - 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
+- 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
 
@@ -86,7 +90,7 @@ Da Vinci runs in this order:
 1. select the active mode
 2. build the correct source artifacts
 3. detect or generate `DA-VINCI.md` as the project visual contract
-4. collect design inputs and register design sources
+4. collect design inputs, prefer project-local `.pen` files under `.da-vinci/designs/`, and register design sources
 5. define or discover the project page map
 6. create or update Pencil designs
 7. bind implementation pages to Pencil pages
@@ -104,6 +108,7 @@ Depending on the mode, the workflow may use these artifacts:
 - `DA-VINCI.md`
 - `.da-vinci/changes/<change-id>/design-brief.md`
 - `.da-vinci/design-registry.md`
+- `.da-vinci/designs/`
 - `.da-vinci/page-map.md`
 - `.da-vinci/changes/<change-id>/proposal.md`
 - `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
@@ -120,6 +125,7 @@ Depending on the mode, the workflow may use these artifacts:
 - `DA-VINCI.md`: project-level visual contract for theme, palette, typography direction, component tone, and page-consistency rules
 - `design-brief.md`: form factor, style, density, brand constraints, and layout preferences
 - `design-registry.md`: project-level `.pen` source inventory
+- `.da-vinci/designs/`: project-local persisted Pencil sources such as `project-baseline.pen` or change-specific `.pen` files
 - `page-map.md`: canonical page list and page responsibilities
 - `proposal.md`: change scope and outcomes
 - `spec.md`: behavior, states, edge cases, and acceptance rules
@@ -145,6 +151,9 @@ project/
 └── .da-vinci/
     ├── project-inventory.md
     ├── design-registry.md
+    ├── designs/
+    │   ├── project-baseline.pen
+    │   └── <change-id>.pen
     ├── page-map.md
     └── changes/
         └── <change-id>/
@@ -164,6 +173,7 @@ Placement rules:
 
 - keep `DA-VINCI.md` at the project root
 - keep project-wide workflow files in `.da-vinci/`
+- keep project-local Pencil files in `.da-vinci/designs/`
 - keep change-specific workflow files in `.da-vinci/changes/<change-id>/`
 - do not scatter `proposal.md`, `tasks.md`, and `verification.md` across the project root
 
@@ -216,21 +226,25 @@ Rules:
 
 - `DA-VINCI.md` is the project-level visual contract for cross-page consistency
 - `design-registry.md` is the project-level inventory of `.pen` sources
+- `.da-vinci/designs/` is the default project-local location for persisted `.pen` files
 - `page-map.md` is the source of truth for implementation pages
 - `pencil-bindings.md` is the source of truth for implementation page -> Pencil page mapping
 
 When a relevant mapping already exists:
 
 - iterate on the mapped Pencil source
+- prefer the project-local `.pen` path already registered in `design-registry.md`
 
 When mappings do not exist but local code exists:
 
 - reconstruct the baseline from the local project
 - rebuild inventory, page map, and design registry
+- save or export the rebuilt Pencil baseline into `.da-vinci/designs/` when possible
 
 When neither mappings nor usable design sources exist:
 
 - create a new Pencil baseline from the current local source of truth
+- persist that baseline under `.da-vinci/designs/` when possible and record the exact path in `design-registry.md`
 
 ## Design input collection
 
@@ -298,9 +312,9 @@ $da-vinci <request>
 Entry helpers:
 
 ```text
-/prompts:dv-intake
-/prompts:dv-prompt
-/prompts:dv-continue
+$da-vinci use intake for <project situation>
+$da-vinci use prompt for <known scenario>
+$da-vinci use continue for <existing workflow state>
 ```
 
 ### Claude
@@ -381,13 +395,20 @@ $da-vinci use feature-change to add a billing page, generate the relevant Pencil
 ### 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.
+$da-vinci use intake for this existing Android project.
+
+I need to globally replace the UI.
+Existing Android 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.
+$da-vinci use continue for this existing redesign-from-code workflow.
+
+Use the existing Da Vinci artifacts.
+Continue into full-delivery.
 ```
 
 ## Workflow examples
@@ -395,6 +416,7 @@ $da-vinci use feature-change to add a billing page, generate the relevant Pencil
 See:
 
 - `docs/prompt-entrypoints.md`
+- `docs/codex-natural-language-usage.md`
 - `docs/workflow-examples.md`
 - `docs/mode-use-cases.md`
 
@@ -403,20 +425,13 @@ See:
 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
@@ -426,9 +441,7 @@ da-vinci/
 │   └── gemini/
 ├── docs/
 │   └── zh-CN/
-├── references/
-│   └── zh-CN/
-└── openspec/
+└── references/
 ```
 
 ## Current status
@@ -438,7 +451,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

@@ -29,15 +29,19 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.6`
+- `@xenonbyte/da-vinci-workflow@0.1.8`
 
 已发布版本重点：
 
+- Codex 的自然语言用法现在有单独文档，明确说明 `intake`、`prompt`、`continue` 和直接 mode 调用方式
+- 项目内 Pencil `.pen` 文件现在明确约定默认持久化到 `.da-vinci/designs/`
+- 设计源登记和工件模板现在会记录项目内优先使用的 `.pen` 路径
 - `intake`、`prompt`、`continue` 三个提示词入口辅助路由已随 Codex、Claude、Gemini 一起发布
-- 主工作流文档、命令说明、示例工件和 OpenSpec 变更文档现在都提供中文配套文档
-- 资产校验现在覆盖完整的 `examples/` 和 `openspec/` 文档集合
+- 中文配套文档现在刻意只保留 `README.zh-CN.md` 和 `docs/zh-CN/`
+- 资产校验现在覆盖完整的随包文档集合
 - `da-vinci status` 会校验 Codex、Claude、Gemini 的完整安装资产
 - Claude 和 Gemini 安装后的命令文案已改为自洽的工作流措辞
+- `.npmrc` 和 `openspec/` 现在只本地保留，不再进入版本管理和 npm 包
 - 安装、卸载、状态、资产校验都通过 Node CLI 提供
 - 仓库内含一个 `greenfield-spec` 的本地 forward test
 
@@ -91,7 +95,7 @@ Da Vinci 的默认顺序是：
 1. 选择 mode
 2. 生成正确的源工件
 3. 检测或生成 `DA-VINCI.md`
-4. 收集设计输入并登记设计源
+4. 收集设计输入，优先使用 `.da-vinci/designs/` 下的项目内 `.pen` 文件，并登记设计源
 5. 定义或发现页面地图
 6. 创建或更新 Pencil 设计
 7. 绑定实现页面到 Pencil 页面
@@ -109,6 +113,7 @@ Da Vinci 的默认顺序是：
 - `DA-VINCI.md`
 - `.da-vinci/changes/<change-id>/design-brief.md`
 - `.da-vinci/design-registry.md`
+- `.da-vinci/designs/`
 - `.da-vinci/page-map.md`
 - `.da-vinci/changes/<change-id>/proposal.md`
 - `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
@@ -125,6 +130,7 @@ Da Vinci 的默认顺序是：
 - `DA-VINCI.md`：项目级视觉契约
 - `design-brief.md`：设计方向、形态、密度、品牌和限制条件
 - `design-registry.md`：项目级 `.pen` 设计源登记
+- `.da-vinci/designs/`：项目内持久化的 Pencil 设计源，例如 `project-baseline.pen` 或按 change 保存的 `.pen` 文件
 - `page-map.md`：页面、职责、状态和共享区域
 - `proposal.md`：范围、目标、非目标和成功标准
 - `spec.md`：行为、状态、边界和验收规则
@@ -134,6 +140,66 @@ Da Vinci 的默认顺序是：
 - `tasks.md`：任务分组和实施顺序
 - `verification.md`：覆盖度和漂移检查
 
+## 工件放置建议
+
+推荐结构：
+
+```text
+project/
+├── DA-VINCI.md
+└── .da-vinci/
+    ├── project-inventory.md
+    ├── design-registry.md
+    ├── designs/
+    │   ├── project-baseline.pen
+    │   └── <change-id>.pen
+    ├── page-map.md
+    └── changes/
+        └── <change-id>/
+            ├── brainstorm.md
+            ├── design-brief.md
+            ├── proposal.md
+            ├── design.md
+            ├── pencil-design.md
+            ├── pencil-bindings.md
+            ├── tasks.md
+            ├── verification.md
+            └── specs/
+                └── <capability>/spec.md
+```
+
+规则：
+
+- `DA-VINCI.md` 放在项目根目录
+- 项目级工作流工件放在 `.da-vinci/`
+- 项目内持久化的 Pencil `.pen` 文件默认放在 `.da-vinci/designs/`
+- change 级工件放在 `.da-vinci/changes/<change-id>/`
+
+## 设计源规则
+
+- `DA-VINCI.md` 是跨页面视觉一致性的项目级视觉契约
+- `design-registry.md` 用来登记项目中的 `.pen` 设计源
+- `.da-vinci/designs/` 是项目内持久化 `.pen` 文件的默认位置
+- `page-map.md` 是实现页面和状态的真相源
+- `pencil-bindings.md` 是实现页面到 Pencil 页面绑定的真相源
+
+当已有页面映射存在时：
+
+- 优先复用已绑定的 Pencil 设计源
+- 如果 `design-registry.md` 里已经登记了 `.da-vinci/designs/` 下的本地 `.pen` 路径，优先使用它
+
+当已有代码存在但还没有映射时：
+
+- 先从当前项目重建设计基线
+- 重建 inventory、page-map、design-registry
+- 在可行时把新的 Pencil 基线保存或导出到 `.da-vinci/designs/`
+
+当既没有映射也没有可用设计源时：
+
+- 基于当前本地真相源创建新的 Pencil 基线
+- 在可行时把基线保存到 `.da-vinci/designs/`
+- 并在 `design-registry.md` 里记录准确路径
+
 ## 安装
 
 安装 npm 包：
@@ -176,9 +242,9 @@ $da-vinci <request>
 辅助入口：
 
 ```text
-/prompts:dv-intake
-/prompts:dv-prompt
-/prompts:dv-continue
+$da-vinci use intake for <project situation>
+$da-vinci use prompt for <known scenario>
+$da-vinci use continue for <existing workflow state>
 ```
 
 ### Claude
@@ -242,19 +308,27 @@ $da-vinci use feature-change to add a billing page, generate the relevant Pencil
 ### 复杂重设计先做 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.
+$da-vinci use intake for this existing Android project.
+
+I need to globally replace the UI.
+Existing Android 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.
+$da-vinci use continue for this existing redesign-from-code workflow.
+
+Use the existing Da Vinci artifacts.
+Continue into full-delivery.
 ```
 
 ## 文档导航
 
 英文文档：
 
+- `docs/codex-natural-language-usage.md`
 - `docs/prompt-entrypoints.md`
 - `docs/workflow-examples.md`
 - `docs/mode-use-cases.md`
@@ -263,20 +337,13 @@ $da-vinci use feature-change to add a billing page, generate the relevant Pencil
 中文文档：
 
 - `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/
@@ -287,7 +354,5 @@ da-vinci/
 │   └── gemini/
 ├── docs/
 │   └── zh-CN/
-├── references/
-│   └── zh-CN/
-└── openspec/
+└── references/
 ```

package/SKILL.md

@@ -70,7 +70,7 @@ Do not stop merely because:
 
 - some pages are still out of scope
 - a future follow-up spec may be needed for untouched behavior
-- a design source should also be saved or exported for better traceability
+- a project-local `.pen` export is still pending for traceability, unless that missing file would make the active design source ambiguous
 
 Those are warnings unless they prevent safe implementation of the current in-scope work.
 
@@ -80,9 +80,12 @@ 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 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`
+- For Codex helper intents, prefer natural-language patterns:
+  - `$da-vinci use intake for <project situation>`
+  - `$da-vinci use prompt for <known scenario>`
+  - `$da-vinci use continue for <existing workflow state>`
+- Claude and Gemini helper routes remain:
+  - `/dv:intake`, `/dv:prompt`, `/dv:continue`
 - Natural-language invocation remains the default path
 
 ## Prompt Entry Routes
@@ -184,7 +187,7 @@ Run the workflow in this order:
 1. Select the active mode
 2. Build the correct source artifacts for that mode
 3. Detect or generate `DA-VINCI.md` as the project visual contract
-4. Collect design inputs and register available design sources
+4. Collect design inputs, prefer project-local `.pen` files under `.da-vinci/designs/`, and register available design sources
 5. Define or discover the project page map
 6. Create or update Pencil designs for the required pages
 7. Bind implementation pages to Pencil pages
@@ -221,14 +224,15 @@ Use these artifacts unless the project defines a different schema:
 3. `DA-VINCI.md`
 4. `.da-vinci/changes/<change-id>/design-brief.md`
 5. `.da-vinci/design-registry.md`
-6. `.da-vinci/page-map.md`
-7. `.da-vinci/changes/<change-id>/proposal.md`
-8. `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
-9. `.da-vinci/changes/<change-id>/design.md`
-10. `.da-vinci/changes/<change-id>/pencil-design.md`
-11. `.da-vinci/changes/<change-id>/pencil-bindings.md`
-12. `.da-vinci/changes/<change-id>/tasks.md`
-13. `.da-vinci/changes/<change-id>/verification.md`
+6. `.da-vinci/designs/`
+7. `.da-vinci/page-map.md`
+8. `.da-vinci/changes/<change-id>/proposal.md`
+9. `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
+10. `.da-vinci/changes/<change-id>/design.md`
+11. `.da-vinci/changes/<change-id>/pencil-design.md`
+12. `.da-vinci/changes/<change-id>/pencil-bindings.md`
+13. `.da-vinci/changes/<change-id>/tasks.md`
+14. `.da-vinci/changes/<change-id>/verification.md`
 
 Not every mode requires every artifact.
 
@@ -254,6 +258,7 @@ Optional artifacts:
 - `DA-VINCI.md`: project-level visual contract for theme, color system, surface treatment, typography direction, and cross-page style rules
 - `design-brief.md`: form factor, visual direction, density, brand constraints, and UI preferences
 - `design-registry.md`: project-level `.pen` file inventory and active design sources
+- `.da-vinci/designs/`: project-local persisted Pencil sources such as `project-baseline.pen` or change-specific `.pen` files
 - `page-map.md`: canonical page list, page responsibilities, route mapping, and page states
 - `proposal.md`: scope, goal, non-goals, and success criteria
 - `spec.md`: behavior, states, inputs, outputs, edge cases, and acceptance rules
@@ -277,10 +282,17 @@ Keep this file at the project root so the visual contract is easy to discover an
 
 - `.da-vinci/project-inventory.md`
 - `.da-vinci/design-registry.md`
+- `.da-vinci/designs/`
 - `.da-vinci/page-map.md`
 
 These files describe project-wide facts that can outlive any one change.
 
+Recommended `.pen` persistence patterns:
+
+- `.da-vinci/designs/project-baseline.pen`
+- `.da-vinci/designs/<change-id>.pen`
+- `.da-vinci/designs/<change-id>/main.pen`
+
 ### Change-level workflow directory
 
 - `.da-vinci/changes/<change-id>/brainstorm.md`
@@ -375,6 +387,8 @@ Do not split page-by-page unless the product is unusually fragmented. Prefer imp
 
 Use `design-registry.md` as the project-level inventory of `.pen` sources.
 
+Use `.da-vinci/designs/` as the default project-local location for persisted Pencil files when the workflow creates or updates them.
+
 Use `DA-VINCI.md` as the project-level visual source of truth for:
 
 - theme and palette
@@ -386,6 +400,7 @@ Use `DA-VINCI.md` as the project-level visual source of truth for:
 When a relevant mapping already exists:
 
 - iterate on the mapped Pencil source
+- prefer the project-local `.pen` file under `.da-vinci/designs/` when one is already registered
 - do not create a new design baseline unless there is a reason
 
 When `DA-VINCI.md` already exists:
@@ -396,6 +411,7 @@ When `DA-VINCI.md` already exists:
 When page-to-Pencil bindings already exist:
 
 - update the mapped Pencil page for the affected implementation page
+- keep the exact `.pen` file path recorded in `design-registry.md`
 
 When project mappings do not exist but existing code exists:
 
@@ -404,12 +420,20 @@ When project mappings do not exist but existing code exists:
 - reconstruct `page-map.md`
 - create or rebuild `design-registry.md`
 - generate a new Pencil baseline only after the inventory is stable
+- save or export that baseline into `.da-vinci/designs/` when possible
 
 When neither mappings nor usable design sources exist:
 
 - state that the project is entering baseline reconstruction
 - create a new Pencil baseline from the current local source of truth
 - generate `DA-VINCI.md` from inferred or user-provided design rules before generating many unrelated pages
+- persist the resulting `.pen` file in `.da-vinci/designs/` when possible and record the path in `design-registry.md`
+
+When a Pencil session cannot yet be exported locally:
+
+- record the live or external source in `design-registry.md`
+- record why local persistence is pending
+- do not hide the lack of a project-local `.pen` path
 
 If the request is too vague to design or implement safely, ask a short clarification question before generating artifacts.
 
@@ -432,11 +456,13 @@ When multiple pages exist:
 - keep one canonical Pencil page or screen per implementation page
 - record the `.pen` file in `design-registry.md`
 - record the mapping in `pencil-bindings.md`
+- persist the active `.pen` file into `.da-vinci/designs/` before closing design work when possible
 
 ## Pencil MCP Rules
 
 When Pencil is available through MCP:
 
+- Prefer the project-local `.pen` file under `.da-vinci/designs/` when one is registered
 - Read the active `.pen` file and page structure before coding
 - read the bound Pencil page for the current implementation page
 - Use Pencil data to extract layout, text, hierarchy, panels, buttons, and content regions