@xenonbyte/da-vinci-workflow 0.1.4 → 0.1.6

package/SKILL.zh-CN.md

@@ -0,0 +1,339 @@
+---
+name: da-vinci
+description: Da Vinci 工作流的中文配套说明。若与 `SKILL.md` 存在差异，以英文原文为准。
+---
+
+# Da Vinci 工作流
+
+> 中文配套文档。英文原文 `SKILL.md` 仍然是工作流的最终权威说明。
+
+Da Vinci 是一个从需求到设计再到代码的交付工作流，用来把产品或页面需求转成结构化规格、Pencil `.pen` 设计、设计绑定、实现任务以及最终代码。
+
+## 核心契约
+
+固定遵守以下规则：
+
+- Requirements 决定行为
+- Pencil 决定呈现
+- Tasks 决定实现顺序
+- Code 必须同时遵循 requirements 和 Pencil 数据
+- 当 requirements 和 Pencil 出现漂移时，先更新源工件，再继续实现
+
+## 执行策略
+
+Da Vinci 默认是 `autonomous-by-default`：
+
+- 不要在每一个步骤都停下来等待确认
+- checkpoint 是内部执行护栏，不是审批点
+- 只有真正的 blocker 才停下
+
+当用户说的是这些意图时，默认当成 `full-delivery`：
+
+- 完成开发
+- 实现生成好的设计
+- 全局重做 UI
+- 把整个项目做完
+
+这种情况下，不要在 `tasks.md` 停住。
+
+## 调用模型
+
+工作流名固定为 `da-vinci`。
+
+- Codex 首选：`$da-vinci <request>`
+- Claude / Gemini 首选：`/da-vinci <request>`
+
+同时提供三个入口辅助动作：
+
+- Codex：`/prompts:dv-intake`、`/prompts:dv-prompt`、`/prompts:dv-continue`
+- Claude / Gemini：`/dv:intake`、`/dv:prompt`、`/dv:continue`
+
+自然语言主入口仍然是默认路径。
+
+## 入口辅助动作
+
+### `intake`
+
+用于用户知道自己要做什么，但不知道怎么写第一条高质量 Da Vinci 提示词。
+
+它应该输出：
+
+- 推荐 mode
+- 推荐 delivery intent
+- 一条主执行提示词
+- 必要时的一条更保守提示词
+- 一条后续 continue 提示词
+- 会实质影响结果的缺失输入
+
+注意：
+
+- `intake` 通常应该生成主工作流提示词
+- 不应该默认把用户直接导向 `build`
+
+### `prompt`
+
+用于用户明确就是想让 Da Vinci 帮他生成场景化提示词。
+
+它应该：
+
+- 生成可复制执行的提示词
+- 明确 behavior source of truth
+- 明确 design source of truth
+- 明确 delivery intent
+- 明确冲突时以谁为准
+
+### `continue`
+
+用于项目里已经存在 `DA-VINCI.md` 或 `.da-vinci/` 工件，工作流需要恢复推进。
+
+它应该：
+
+- 先检查现有工件
+- 判断当前停在哪个阶段
+- 输出一条可直接继续的提示词
+- 不要在工件已经足够时重新开始 discovery
+
+## Mode 选择
+
+支持四种模式：
+
+1. `greenfield-spec`
+   - 新项目
+   - 需求已经足够清晰
+
+2. `greenfield-brainstorm`
+   - 新项目
+   - 输入仍然发散，需要先收敛
+
+3. `redesign-from-code`
+   - 已有项目
+   - 代码是当前行为真相
+   - 目标是广泛或全局重设计
+
+4. `feature-change`
+   - 已有项目
+   - 目标是局部功能或页面修改
+
+如果用户没指定 mode：
+
+- 新项目且需求清晰：`greenfield-spec`
+- 新项目但想法发散：`greenfield-brainstorm`
+- 现有项目全局 UI 替换：`redesign-from-code`
+- 现有项目局部修改：`feature-change`
+
+## 设计输入收集
+
+在大范围生成 Pencil 页面前，先收集或推断：
+
+1. `DA-VINCI.md` 是否已存在
+2. 产品形态
+   - desktop software
+   - web app
+   - tablet
+   - mobile app
+3. 视觉方向
+   - tone
+   - density
+   - brand direction
+   - dark / light
+4. 设计限制
+   - 现有品牌
+   - 现有设计系统
+   - 响应式优先级
+   - 交付限制
+
+优先级：
+
+1. `DA-VINCI.md`
+2. 现有工作流工件
+3. 项目代码和本地信号
+4. 用户明确回答
+5. 简短澄清问题
+
+## 默认工作流
+
+标准顺序：
+
+1. 选择 mode
+2. 生成该 mode 所需的起始工件
+3. 检测或生成 `DA-VINCI.md`
+4. 收集设计输入并登记设计源
+5. 定义或发现页面地图
+6. 创建或更新 Pencil 设计
+7. 绑定实现页面到 Pencil 页面
+8. 通过 MCP 读取 Pencil 设计数据
+9. 生成实现任务
+10. 根据 requirements 和 Pencil 数据实现代码
+11. 在结束前检查需求漂移和设计漂移
+
+完成规则：
+
+- 用户明确说 `plan-only` 时，只做到规划工件
+- 用户明确说 `design-only` 时，只做到设计工件和绑定
+- 其他情况默认 `full-delivery`
+
+## 按需加载参考文档
+
+只加载当前步骤需要的 reference：
+
+- `references/modes.md`
+- `references/artifact-templates.md`
+- `references/checkpoints.md`
+- `references/design-inputs.md`
+- `references/page-mapping.md`
+- `references/pencil-design-to-code.md`
+- `references/platform-adapters.md`
+- `references/prompt-recipes.md`
+
+## 默认工件
+
+默认工件集合：
+
+1. `.da-vinci/changes/<change-id>/brainstorm.md`
+2. `.da-vinci/project-inventory.md`
+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`
+
+## 工件放置规则
+
+- `DA-VINCI.md` 放项目根目录
+- 项目级工件放 `.da-vinci/`
+- 变更级工件放 `.da-vinci/changes/<change-id>/`
+
+## 各模式最低工件流
+
+### `greenfield-spec`
+
+`DA-VINCI` -> `design-brief` -> `proposal` -> `specs` -> `page-map` -> `design-registry` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
+
+### `greenfield-brainstorm`
+
+`brainstorm` -> `DA-VINCI` -> `design-brief` -> `proposal` -> `specs` -> `page-map` -> `design-registry` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
+
+### `redesign-from-code`
+
+`project-inventory` -> `DA-VINCI` -> `design-registry` -> `proposal` -> `specs` -> `page-map` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
+
+广泛重设计时，`specs/` 要按 redesign slice 拆分，不要只做一个巨大的 `ui-refresh/spec.md`。
+
+### `feature-change`
+
+`proposal` -> `specs` -> 受影响的 `page-map` -> `DA-VINCI` -> `design-registry` -> `design` -> `pencil-design` delta -> `pencil-bindings` delta -> `tasks` -> `verification`
+
+## Requirement 拆解规则
+
+在设计或编码之前：
+
+- 把请求拆成 pages、flows、states 和数据依赖
+- 分清视觉问题、行为问题、集成问题
+- 明确 must-have 和后续改进项
+- 尽早标记高风险区域：auth、permission、upload、payment、admin、secret、migration
+
+对于 `redesign-from-code`：
+
+- 先 inventory 现有 routes、pages、modules
+- 区分保留的 behavior 和需要替换的 presentation
+- 当一个 spec 太粗时，按 redesign slice 拆开
+
+## 设计源规则
+
+- `design-registry.md` 是项目级 `.pen` 设计源清单
+- `DA-VINCI.md` 是项目级视觉契约
+- 已有绑定时，优先沿用并迭代现有 Pencil 源
+- 现有代码存在但映射缺失时，先做 baseline reconstruction
+- 既没有映射也没有设计源时，明确说明项目进入 baseline reconstruction
+
+## Pencil 规则
+
+Pencil 是结构化设计源，不是静态截图源。
+
+创建或编辑 Pencil 设计时：
+
+- 基于当前 scope 需要的页面来做
+- 遵循 `page-map.md`
+- 页面名、section 名、label 尽量和 spec 对齐
+- 对实现有影响的 states 要显式建模
+- 设计完成后做一次视觉检查，再视为可实现
+
+## Pencil MCP 规则
+
+当 Pencil 通过 MCP 可用时：
+
+- 先读 active `.pen` 文件和目标页面结构
+- 读取布局、文本、层级、按钮、面板和内容分区
+- screenshot 只做次要视觉辅助
+
+当 Pencil 不可用时：
+
+- 明确说明设计支撑路径缺失
+- 退回 requirements-first 的实现方式
+
+## 实现规则
+
+编码时：
+
+- requirements 决定行为、条件、状态和语义
+- Pencil 决定布局、section 顺序、视觉分组和文案放置
+- 使用 `pencil-bindings.md` 决定当前页面应跟随哪个 Pencil 页面
+- 不要从设计外观中虚构新行为
+- 也不要在写代码时忽略 Pencil 的结构
+
+## Checkpoints
+
+需要运行的 checkpoints：
+
+1. `discovery checkpoint`
+2. `spec checkpoint`
+3. `design checkpoint`
+4. `mapping checkpoint`
+5. `task checkpoint`
+6. `execution checkpoint`
+
+状态：
+
+- `PASS`
+- `WARN`
+- `BLOCK`
+
+处理方式：
+
+- `PASS`：自动继续
+- `WARN`：记录问题并继续
+- `BLOCK`：停止，报告 blocker，只有在无法从现有工件或本地上下文解决时才询问用户
+
+## 漂移策略
+
+以下都算 drift：
+
+- requirements 改了，但 Pencil 没更新
+- page map 变了，但 bindings 没更新
+- design registry 变了，但下游绑定没更新
+- Pencil 变了，但 tasks 没更新
+- 代码行为超出批准范围
+- 代码布局或内容结构明显偏离 Pencil 且没有记录原因
+
+发现 drift 时：
+
+- 先更新源工件
+- 再继续实现
+
+## 输出格式
+
+在完成有意义的工作后，报告：
+
+1. 改动了哪些文件
+2. 当前 active mode
+3. 当前 workflow state
+4. 下一步建议
+5. blockers 或 drift
+
+保持简洁、可执行、面向交付。

package/commands/claude/da-vinci.md

@@ -3,12 +3,15 @@ description: Da Vinci workflow command index for Claude
 ---
 # Da Vinci
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 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,5 +22,6 @@ Notes:
 - Requirements decide behavior.
 - Pencil decides presentation.
 - Code must follow both.
-- Use `references/platform-adapters.md` for shared invocation rules.
-- Use `references/checkpoints.md` when running workflow checkpoints.
+- 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/breakdown.md

@@ -3,7 +3,7 @@ description: Break requirements into scope, flows, states, and specs for Da Vinc
 ---
 # Da Vinci Breakdown
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `breakdown`
 

package/commands/claude/dv/build.md

@@ -3,7 +3,7 @@ description: Build software from requirements and Pencil design data for Da Vinc
 ---
 # Da Vinci Build
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `build`
 

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/design.md

@@ -3,7 +3,7 @@ description: Create or refine Pencil-backed design plans for Da Vinci.
 ---
 # Da Vinci Design
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `design`
 

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/claude/dv/tasks.md

@@ -3,7 +3,7 @@ description: Generate implementation tasks from requirements and Pencil designs
 ---
 # Da Vinci Tasks
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `tasks`
 

package/commands/claude/dv/verify.md

@@ -3,7 +3,7 @@ description: Verify requirement coverage, Pencil coverage, and drift for Da Vinc
 ---
 # Da Vinci Verify
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `verify`
 

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

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

@@ -0,0 +1,27 @@
+---
+description: Da Vinci intake route for Codex.
+---
+# Da Vinci Intake
+
+Use the `da-vinci` skill for this request.
+
+Action: `intake`
+
+Goal:
+- 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: `plan-only`, `design-only`, or `full-delivery`
+- 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 `/prompts:dv-build`
+- `intake` should usually produce a main workflow prompt, not a build-only prompt
+- prefer `redesign-from-code` or `feature-change` when the request starts from an existing project

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

@@ -0,0 +1,24 @@
+---
+description: Da Vinci prompt-builder route for Codex.
+---
+# Da Vinci Prompt
+
+Use the `da-vinci` skill for this request.
+
+Action: `prompt`
+
+Goal:
+- generate copy-ready Da Vinci 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 the behavior source of truth
+- state the design reference source
+- state the desired delivery intent
+- state how conflicts should be resolved
+- make state, subpage, and overlay coverage explicit when the project is complex

package/commands/gemini/da-vinci.toml

@@ -5,12 +5,15 @@ description: Da Vinci workflow command index for Gemini
 ---
 # Da Vinci
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Platform: Gemini
 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.
@@ -21,6 +24,8 @@ 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 Claude, Codex, and Gemini.
 
 """

package/commands/gemini/dv/breakdown.toml

@@ -2,7 +2,7 @@ description = "Break requirements into scope, flows, states, and specs for Da Vi
 prompt = """
 # Da Vinci Breakdown
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `breakdown`
 

package/commands/gemini/dv/build.toml

@@ -2,7 +2,7 @@ description = "Build software from requirements and Pencil design data for Da Vi
 prompt = """
 # Da Vinci Build
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `build`
 

package/commands/gemini/dv/continue.toml

@@ -0,0 +1,24 @@
+description = "Generate the best continuation prompt from existing Da Vinci artifacts."
+prompt = """
+# 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/gemini/dv/design.toml

@@ -2,7 +2,7 @@ description = "Create or refine Pencil-backed design plans for Da Vinci."
 prompt = """
 # Da Vinci Design
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `design`