@xenonbyte/da-vinci-workflow 0.1.4 → 0.1.6

package/openspec/changes/da-vinci-v2-1-workflow/specs/workflow/spec.md

@@ -0,0 +1,50 @@
+# Spec
+
+## Capability
+- Name: `Da Vinci workflow definition`
+
+## Behavior
+- The workflow SHALL support four modes: `greenfield-spec`, `greenfield-brainstorm`, `redesign-from-code`, and `feature-change`.
+- The workflow SHALL define how design inputs are collected before new Pencil design generation for greenfield work.
+- The workflow SHALL define a project-level registry for `.pen` design sources.
+- The workflow SHALL detect or generate `DA-VINCI.md` before broad Pencil design generation and SHALL use it as the project-level visual contract.
+- The workflow SHALL define implementation page to Pencil page bindings.
+- The workflow SHALL define when broad `redesign-from-code` work must split into multiple redesign-slice specs instead of one oversized `ui-refresh` spec.
+- The workflow SHALL define a fallback policy for missing mappings and missing design sources.
+- The workflow SHALL run as autonomous-by-default and SHALL not stop for user confirmation at each stage.
+- The workflow SHALL treat checkpoints as internal execution guards rather than approval gates.
+- The repository SHALL contain a README that explains the workflow, modes, artifacts, checkpoints, and platform usage.
+
+## States
+- Greenfield with clear requirements
+- Greenfield with unstable brainstorm input
+- Existing codebase with redesign scope
+- Existing codebase with feature-change scope
+- Mapping present
+- Mapping missing
+
+## Inputs
+- Product or feature requirements
+- Existing codebase structure when available
+- Existing `.pen` files when available
+- Design preferences and form factor information
+
+## Outputs
+- Updated workflow definition in the skill
+- Project-level documentation in `README.md`
+- OpenSpec planning artifacts describing the change
+
+## Acceptance
+- A reader can identify the correct mode for a given project start condition.
+- A reader can identify which artifact holds design source inventory.
+- A reader can identify that `DA-VINCI.md` is the project-level visual contract.
+- A reader can identify which artifact binds implementation pages to Pencil pages.
+- A reader can identify when one redesign spec is too coarse and should be split into redesign slices.
+- A reader can identify what happens when no mapping exists.
+- A reader can identify that the workflow continues automatically unless a real blocker exists.
+- A reader can identify how to invoke the skill on Codex, Claude, and Gemini.
+
+## Edge Cases
+- Existing codebase has no registered Pencil design source
+- Multiple `.pen` files exist and only one should be treated as primary
+- Greenfield work lacks explicit design preference input

package/openspec/changes/da-vinci-v2-1-workflow/specs/workflow/spec.zh-CN.md

@@ -0,0 +1,50 @@
+# Spec
+
+## 能力
+- 名称：`Da Vinci workflow definition`
+
+## 行为
+- 工作流必须支持四种模式：`greenfield-spec`、`greenfield-brainstorm`、`redesign-from-code` 和 `feature-change`。
+- 工作流必须定义在 greenfield 工作中，生成新的 Pencil 设计之前如何收集设计输入。
+- 工作流必须定义一个项目级 `.pen` 设计源登记机制。
+- 工作流必须在大范围 Pencil 设计生成前检测或生成 `DA-VINCI.md`，并将其作为项目级视觉契约使用。
+- 工作流必须定义实现页面到 Pencil 页面的绑定方式。
+- 工作流必须定义在大范围 `redesign-from-code` 工作中，何时应拆成多个 redesign-slice spec，而不是一个过大的 `ui-refresh` spec。
+- 工作流必须定义在缺少映射或缺少设计源时的回退策略。
+- 工作流必须默认以 autonomous-by-default 运行，而不是在每个阶段都停下来等待用户确认。
+- 工作流必须把 checkpoint 视为内部执行保护，而不是审批闸门。
+- 仓库必须包含一份 README，用来说明工作流、模式、工件、检查点和平台使用方式。
+
+## 状态
+- 需求明确的 greenfield
+- 输入仍在发散中的 greenfield brainstorm
+- 需要重设计的现有代码库
+- 需要 feature-change 的现有代码库
+- 映射已存在
+- 映射缺失
+
+## 输入
+- 产品或功能需求
+- 可用时的现有代码库结构
+- 可用时的现有 `.pen` 文件
+- 设计偏好和产品形态信息
+
+## 输出
+- skill 中更新后的工作流定义
+- `README.md` 中的项目级说明文档
+- 描述该变更的 OpenSpec 规划工件
+
+## 验收
+- 读者可以根据给定项目起点识别正确 mode。
+- 读者可以识别哪个工件负责保存设计源清单。
+- 读者可以识别 `DA-VINCI.md` 是项目级视觉契约。
+- 读者可以识别哪个工件负责绑定实现页面到 Pencil 页面。
+- 读者可以识别何时一个 redesign spec 过于粗糙，需要拆成多个 redesign slice。
+- 读者可以识别在没有映射时会发生什么。
+- 读者可以识别工作流会在没有真实阻塞时自动继续。
+- 读者可以识别如何在 Codex、Claude 和 Gemini 中调用这个 skill。
+
+## 边界情况
+- 现有代码库没有登记 Pencil 设计源
+- 存在多个 `.pen` 文件，但只有一个应该视为主源
+- greenfield 工作缺少明确的设计偏好输入

package/openspec/changes/da-vinci-v2-1-workflow/tasks.md

@@ -0,0 +1,31 @@
+# Tasks
+
+## 1. Workflow Definition
+- [x] Add four workflow modes to the skill
+- [x] Add design input collection rules
+- [x] Add design source registration rules
+- [x] Add fallback policy for missing mappings
+- [x] Add explicit page-mapping and design-input rules to support traceable implementation
+- [x] Add `DA-VINCI.md` as a project-level visual contract checked before broad Pencil design generation
+- [x] Add redesign-slice spec partitioning rules for broad `redesign-from-code` work
+
+## 2. Artifact Definition
+- [x] Add `DA-VINCI.md`
+- [x] Add `design-brief.md`
+- [x] Add `design-registry.md`
+- [x] Strengthen `page-map.md`
+- [x] Strengthen `pencil-bindings.md`
+
+## 3. Checkpoints
+- [x] Update `discovery checkpoint`
+- [x] Update `design checkpoint`
+- [x] Update `mapping checkpoint`
+- [x] Update `spec checkpoint` to catch oversized redesign specs
+- [x] Define autonomous-by-default execution policy
+
+## 4. Repository Documentation
+- [x] Add `README.md`
+- [x] Add workflow examples
+
+## 5. Planning
+- [x] Add OpenSpec artifacts for this workflow change

package/openspec/changes/da-vinci-v2-1-workflow/tasks.zh-CN.md

@@ -0,0 +1,31 @@
+# Tasks
+
+## 1. 工作流定义
+- [x] 为 skill 添加四种工作流模式
+- [x] 添加设计输入收集规则
+- [x] 添加设计源登记规则
+- [x] 添加映射缺失时的回退策略
+- [x] 添加明确的页面映射与设计输入规则，以支持可追溯的实现
+- [x] 添加 `DA-VINCI.md` 作为项目级视觉契约，并在大范围 Pencil 设计生成前检查
+- [x] 为大范围 `redesign-from-code` 工作添加 redesign-slice spec 拆分规则
+
+## 2. 工件定义
+- [x] 添加 `DA-VINCI.md`
+- [x] 添加 `design-brief.md`
+- [x] 添加 `design-registry.md`
+- [x] 强化 `page-map.md`
+- [x] 强化 `pencil-bindings.md`
+
+## 3. 检查点
+- [x] 更新 `discovery checkpoint`
+- [x] 更新 `design checkpoint`
+- [x] 更新 `mapping checkpoint`
+- [x] 更新 `spec checkpoint`，用于拦截过大的 redesign spec
+- [x] 定义 autonomous-by-default 执行策略
+
+## 4. 仓库文档
+- [x] 添加 `README.md`
+- [x] 添加 workflow examples
+
+## 5. 规划
+- [x] 为本次工作流变更添加 OpenSpec 工件

package/openspec/config.yaml

@@ -0,0 +1,11 @@
+schema: spec-driven
+language: en
+profile: expanded
+context:
+  project: da-vinci
+  domain: requirement-to-design-to-code workflow
+rules:
+  implementation_contract:
+    - requirements decide behavior
+    - Pencil decides presentation
+    - code follows both

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js"
   },
   "files": [
     "SKILL.md",
+    "SKILL.zh-CN.md",
     "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "CHANGELOG.zh-CN.md",
     "agents",
     "commands",
     "references",
     "docs",
     "examples",
+    "openspec",
     "bin",
     "lib",
     "scripts",

package/references/checkpoints.md

@@ -19,6 +19,10 @@ Default execution intent:
 - assume `full-delivery` unless the request explicitly says `plan-only`, `design-only`, or another partial-delivery goal
 - in `full-delivery`, checkpoints do not end the workflow; they control whether the workflow continues safely
 
+Resume rule:
+
+- when artifacts already exist and the workflow was paused, `continue` should resume from the current artifact truth instead of restarting discovery
+
 ## Visual Contract Rule
 
 Before broad Pencil page generation:

package/references/platform-adapters.md

@@ -25,7 +25,19 @@ Use this for:
 - Pencil page generation planning
 - design-to-code implementation
 
-If explicit routes are added later, treat them as routing helpers, not the only entrypoint.
+Explicit helper routes:
+
+```text
+/prompts:dv-intake
+/prompts:dv-prompt
+/prompts:dv-continue
+```
+
+Use them when:
+
+- the first workflow prompt is hard to phrase
+- the user wants copy-ready prompt text
+- the workflow needs to resume from existing artifacts
 
 ## Claude
 
@@ -43,6 +55,14 @@ Use the same workflow stages as Codex:
 - implementation
 - verification
 
+Explicit helper routes:
+
+```text
+/dv:intake
+/dv:prompt
+/dv:continue
+```
+
 ## Gemini
 
 Preferred:
@@ -53,6 +73,14 @@ Preferred:
 
 Keep the same artifact names and checkpoint names across platforms.
 
+Explicit helper routes:
+
+```text
+/dv:intake
+/dv:prompt
+/dv:continue
+```
+
 ## Cross-Platform Rule
 
 Keep these stable:
@@ -62,5 +90,6 @@ Keep these stable:
 - drift policy
 - requirement/design/code contract
 - mode names
+- prompt helper semantics
 
 Platform adapters may differ in command syntax, but not in workflow semantics.

package/references/prompt-recipes.md

@@ -0,0 +1,181 @@
+# Prompt Recipes
+
+Use this reference when users need help starting or resuming Da Vinci but do not know which prompt to run.
+
+## Route Purposes
+
+Use these helper actions:
+
+- `intake`: choose the best mode and generate the best first workflow prompt
+- `prompt`: generate scenario-specific prompt text directly
+- `continue`: inspect existing artifacts and generate the best continuation prompt
+
+## Route Discipline
+
+Keep these rules fixed:
+
+- `intake` and `continue` should usually output a main `$da-vinci ...` or `/da-vinci ...` prompt
+- do not default `intake` or `continue` into `build`
+- use `build` directly only when tasks, design bindings, and implementation readiness are already clear
+- continuation prompts should preserve existing artifact truth instead of restarting discovery
+
+## Truth Sources To Capture
+
+Good prompt output should explicitly state:
+
+1. behavior source of truth
+   - existing codebase
+   - formal specs
+   - approved requirements
+
+2. presentation or design source of truth
+   - Pencil `.pen` files
+   - HTML references
+   - Figma exports
+   - existing project visual contract
+
+3. delivery intent
+   - `plan-only`
+   - `design-only`
+   - `full-delivery`
+
+4. conflict rule
+   - if design and code conflict, which truth wins
+
+5. coverage expectations
+   - states
+   - subpages
+   - dialogs
+   - sheets
+   - nested flows
+
+## Output Shape For `intake`
+
+`intake` should normally 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
+
+Use `intake` when:
+
+- the user has a complex existing project
+- the user has multiple truth sources and is unsure how to frame them
+- the user asks "how should I use Da Vinci for this?"
+
+## Output Shape For `prompt`
+
+`prompt` should normally output:
+
+- one primary prompt
+- one more conservative prompt when useful
+- one continuation prompt when useful
+
+Use `prompt` when:
+
+- the user already knows the scenario
+- the user explicitly asks for copy-ready prompt text
+- the user wants a reusable team template
+
+## Output Shape For `continue`
+
+`continue` should normally:
+
+- inspect `DA-VINCI.md`
+- inspect `.da-vinci/project-inventory.md` when present
+- inspect `.da-vinci/design-registry.md` when present
+- inspect `.da-vinci/page-map.md` when present
+- inspect current change artifacts under `.da-vinci/changes/<change-id>/`
+
+Then output:
+
+- detected workflow state
+- missing or weak artifacts
+- one executable continuation prompt
+- one more conservative continuation prompt when useful
+
+Use `continue` when:
+
+- the workflow paused after inventory
+- the workflow paused after specs
+- the workflow paused after tasks
+- the user asks how to resume without restarting from scratch
+
+## Mode Heuristics
+
+Choose the mode using these heuristics:
+
+- `greenfield-spec`
+  - new project
+  - requirements are already clear
+
+- `greenfield-brainstorm`
+  - new project
+  - ideas are still rough or contradictory
+
+- `redesign-from-code`
+  - existing product
+  - behavior should stay grounded in current code
+  - broad or global UI replacement
+
+- `feature-change`
+  - existing product
+  - scoped requirement, page, or flow change
+
+## Scenario Recipe: Existing Project Global UI Replacement
+
+Prefer:
+
+- mode: `redesign-from-code`
+- behavior truth: existing code
+- presentation truth: HTML, Pencil, or other design references
+- delivery intent: usually `full-delivery`
+
+Prompt should make these explicit:
+
+- preserve current behavior
+- preserve integrations and state transitions
+- inventory all screens and states
+- split redesign into implementation-safe slices
+- document gaps between code and design references
+
+## Scenario Recipe: Existing Code Plus HTML References
+
+Prompt should explicitly say:
+
+- the code is the behavior source of truth
+- the HTML directory is a presentation reference only
+- conflicts must preserve behavior and record the mismatch
+- the workflow should inspect page states, subpages, dialogs, and overlays carefully
+
+## Scenario Recipe: Continue After Inventory
+
+If the project already has:
+
+- `project-inventory.md`
+- `page-map.md`
+- early specs or proposal work
+
+Then `continue` should usually produce a prompt that:
+
+- keeps current artifacts as the working baseline
+- completes any missing design mapping
+- moves into tasks
+- proceeds into implementation if the delivery intent is `full-delivery`
+
+## Scenario Recipe: Continue After Tasks
+
+If the project already has:
+
+- `tasks.md`
+- valid spec slices
+- design bindings or an explicit design gap record
+
+Then `continue` should usually produce a prompt that:
+
+- resumes from the current task checkpoint
+- starts implementation immediately unless a real blocker exists
+- keeps execution checkpoints active after each top-level task group

package/references/zh-CN/artifact-templates.md

@@ -0,0 +1,163 @@
+# 工件模板
+
+> 中文配套文档。若与英文原文存在差异，请以 `references/artifact-templates.md` 为准。
+
+本文定义 Da Vinci 默认工件的推荐结构。
+
+## 放置规则
+
+- `DA-VINCI.md` 放项目根目录
+- 项目级工件放 `.da-vinci/`
+- 变更级工件放 `.da-vinci/changes/<change-id>/`
+
+推荐布局：
+
+```text
+project/
+├── DA-VINCI.md
+└── .da-vinci/
+    ├── project-inventory.md
+    ├── design-registry.md
+    ├── 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
+```
+
+## 关键模板说明
+
+### `brainstorm.md`
+
+用于收敛早期想法，记录：
+
+- 输入
+- 产品方向
+- 候选页面
+- 候选流程
+- 风险与未知项
+
+### `project-inventory.md`
+
+用于从现有代码盘点：
+
+- 当前产品概况
+- 路由和页面
+- 共享 UI 区域
+- 技术限制
+- 重设计影响范围
+
+### `DA-VINCI.md`
+
+用于项目级视觉契约，记录：
+
+- 产品形态
+- 视觉方向
+- 主题
+- 排版
+- 布局规则
+- 组件语气
+- Do / Do Not
+- Source Of Truth
+
+### `design-brief.md`
+
+用于记录：
+
+- 产品形态
+- 视觉方向
+- 品牌约束
+- 布局优先级
+- 明确或推断出的偏好
+
+### `design-registry.md`
+
+用于记录：
+
+- 活跃 `.pen` 源
+- 首选设计源
+- 历史或次要设计源
+- 设计源说明
+
+### `page-map.md`
+
+用于记录：
+
+- canonical pages
+- 每个页面的状态
+- 共享区域
+- 页面优先级
+
+### `proposal.md`
+
+用于记录：
+
+- 变更目标
+- 范围
+- 非目标
+- 风险
+- 成功标准
+
+### `spec.md`
+
+用于记录：
+
+- capability 名称
+- behavior
+- states
+- inputs
+- outputs
+- acceptance
+- edge cases
+
+### `design.md`
+
+用于记录：
+
+- 页面结构
+- 交互模型
+- 布局策略
+- 组件策略
+
+### `pencil-design.md`
+
+用于记录：
+
+- 活跃 `.pen` 源
+- 屏幕和 screen id
+- 实现说明
+- 校验说明
+
+### `pencil-bindings.md`
+
+用于记录：
+
+- 实现页面到 Pencil 页面映射
+- 共享区域到设计区域映射
+- 设计源说明
+
+### `tasks.md`
+
+用于记录：
+
+- 顶层任务组
+- 依赖顺序
+- checkpoint 状态
+
+### `verification.md`
+
+用于记录：
+
+- checkpoint 汇总
+- requirement coverage
+- design coverage
+- drift findings
+- known gaps