@xenonbyte/da-vinci-workflow 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.1.18 - 2026-03-28
+
+### Added
+- `overhaul-from-code` as a fifth workflow mode for broad existing-product rewrites where the current codebase remains migration evidence, but new `proposal.md` and `specs/` become the target behavior truth
+- `migration-contract.md` as a first-class change artifact for preserve / revise / retire / unknown decisions in overhaul work
+- `docs/dv-command-reference.md` and `docs/zh-CN/dv-command-reference.md` to explain route responsibilities, stateful next-step recommendations, and verify rollback behavior
+
+### Changed
+- intake, mode guides, prompt recipes, workflow examples, and natural-language usage now distinguish `overhaul-from-code` from `redesign-from-code` instead of forcing large product rewrites into UI-only redesign semantics
+- workflow, checkpoint, and design-input guidance now require overhaul runs to stabilize `proposal.md`, `migration-contract.md`, target `specs/`, and `page-map.md` before broad Pencil generation
+- visual-adapter and Pencil design guidance now explain how `overhaul-from-code` keeps current code as reference evidence while using the new truth sources to drive design and implementation
+- prompt preset docs now include dedicated `overhaul-from-code` intake, breakdown, design, and continue templates for mobile, desktop, web, and tablet surfaces
+- page-mapping, checkpoint, and command-reference docs now explain how to recover when bindings still exist but either implementation or the design source is missing
+
 ## v0.1.17 - 2026-03-28
 
 ### Added

package/README.md

@@ -21,13 +21,14 @@ This workflow is intended for:
 - 0-to-1 product delivery
 - brainstorm-to-product delivery
 - redesign from existing code
+- large existing-product overhauls where flows and logic also change
 - scoped feature delivery on an existing product
 
 ## Current release
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.1.16`
+- `@xenonbyte/da-vinci-workflow@0.1.18`
 
 Release highlights:
 
@@ -70,7 +71,7 @@ Release highlights:
 
 ## Supported workflow modes
 
-Da Vinci V2 supports four modes.
+Da Vinci currently supports five modes.
 
 ### `greenfield-spec`
 
@@ -84,6 +85,10 @@ Use when the project is new but the inputs come from multiple rounds of rough pr
 
 Use when an existing project already has routes, pages, and UI, and the goal is a broad redesign or UI replacement.
 
+### `overhaul-from-code`
+
+Use when an existing project is undergoing a broad system-level rewrite and current code is still valuable as migration evidence, but no longer the complete target behavior truth.
+
 ### `feature-change`
 
 Use when an existing product needs a scoped requirement change, page addition, or page update.
@@ -225,6 +230,7 @@ Depending on the mode, the workflow may use these artifacts:
 - `project-inventory.md`: current routes, pages, and UI patterns from an existing codebase
 - `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
+- `migration-contract.md`: preserve / revise / retire / unknown boundaries for existing-system overhaul work
 - `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
@@ -242,6 +248,8 @@ Use specs as capability or redesign-slice boundaries, not as page counters.
 
 For broad `redesign-from-code` work, prefer multiple `specs/<slice>/spec.md` files over one oversized `ui-refresh/spec.md`.
 
+For broad `overhaul-from-code` work, prefer multiple `specs/<slice>/spec.md` files plus one `migration-contract.md` over one oversized rewrite spec that mixes preserved and retired system behavior.
+
 ## Artifact placement
 
 Recommended project layout:
@@ -260,6 +268,7 @@ project/
         └── <change-id>/
             ├── brainstorm.md
             ├── design-brief.md
+            ├── migration-contract.md
             ├── proposal.md
             ├── design.md
             ├── pencil-design.md
@@ -332,6 +341,7 @@ Rules:
 - `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
 - in `redesign-from-code`, existing code is behavior truth, not layout truth
+- in `overhaul-from-code`, existing code is reference evidence and migration baseline, not automatic final behavior truth
 - complex pages should be decomposed into subpages, states, overlays, and implementation surfaces before Pencil redesign is treated as final
 - the preferred `.pen` path recorded in `design-registry.md` is workflow-owned state, not user-authored config
 - when Pencil work starts, Da Vinci should use or create that exact project-local `.pen` path instead of relying on whichever Pencil document happens to be active
@@ -562,6 +572,12 @@ $da-vinci use greenfield-brainstorm to turn several product ideas into a page ma
 $da-vinci use redesign-from-code to inventory the existing app, identify current pages, and generate a new Pencil-backed UI plan
 ```
 
+### Overhaul from code
+
+```text
+$da-vinci use overhaul-from-code to inventory the current product, define preserve/revise/retire boundaries, rewrite the target flows and specs, and generate a Pencil-backed overhaul plan
+```
+
 ### Feature change
 
 ```text
@@ -587,13 +603,25 @@ Use the existing Da Vinci artifacts.
 Continue into full-delivery.
 ```
 
+### Continue after overhaul planning
+
+```text
+$da-vinci use continue for this existing overhaul-from-code workflow.
+
+Use the existing Da Vinci artifacts.
+Continue from proposal, migration-contract, and target specs into design or implementation.
+```
+
 ## Workflow examples
 
 See:
 
 - `docs/prompt-entrypoints.md`
+- `docs/dv-command-reference.md`
 - `docs/prompt-presets/`
   - includes `Simple redesign`, `Complex redesign`, `Design-only`, and `Continue` variants in each surface file
+- `docs/workflow-overview.md`
+- `docs/pencil-rendering-workflow.md`
 - `docs/codex-natural-language-usage.md`
 - `docs/visual-adapters.md`
 - `docs/visual-assist-presets/`
@@ -605,8 +633,11 @@ See:
 Chinese companion documents are included in this repository:
 
 - `README.zh-CN.md`
+- `docs/zh-CN/dv-command-reference.md`
 - `docs/zh-CN/prompt-presets/`
   - each surface file also includes `Simple redesign`, `Complex redesign`, `Design-only`, and `Continue`
+- `docs/zh-CN/workflow-overview.md`
+- `docs/zh-CN/pencil-rendering-workflow.md`
 - `docs/zh-CN/visual-adapters.md`
 - `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`

package/README.zh-CN.md

@@ -23,13 +23,14 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 - 0 到 1 的产品交付
 - 从 brainstorming 走向可实施产品
 - 基于现有代码做全局 UI 重设计
+- 基于现有代码做流程、逻辑和 UI 一起变化的大改版
 - 在现有产品上做范围明确的 feature-change
 
 ## 当前发布状态
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.1.16`
+- `@xenonbyte/da-vinci-workflow@0.1.18`
 
 已发布版本重点：
 
@@ -72,7 +73,7 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 ## 支持的工作流模式
 
-Da Vinci V2 支持四种模式：
+Da Vinci 当前支持五种模式：
 
 ### `greenfield-spec`
 
@@ -86,6 +87,10 @@ Da Vinci V2 支持四种模式：
 
 已有项目，代码和行为已存在，目标是做广泛或全局的 UI 重设计。
 
+### `overhaul-from-code`
+
+已有项目，但目标是做系统级大改版；现有代码仍然是迁移基线和参考证据，但不再天然等于新版本的最终行为真相。
+
 ### `feature-change`
 
 已有项目，只做某个功能、页面、流程的局部修改。
@@ -230,6 +235,7 @@ Da Vinci 的默认顺序是：
 - `project-inventory.md`：现有代码库里的路由、页面、UI 结构盘点
 - `DA-VINCI.md`：项目级视觉契约
 - `design-brief.md`：设计方向、形态、密度、品牌和限制条件
+- `migration-contract.md`：存量系统在大改版中哪些保留、修改、废弃、待确认的边界
 - `design-registry.md`：项目级 `.pen` 设计源登记
 - `.da-vinci/designs/`：项目内持久化的 Pencil 设计源，例如 `project-baseline.pen` 或按 change 保存的 `.pen` 文件
 - `page-map.md`：页面、职责、状态和共享区域
@@ -259,6 +265,7 @@ project/
         └── <change-id>/
             ├── brainstorm.md
             ├── design-brief.md
+            ├── migration-contract.md
             ├── proposal.md
             ├── design.md
             ├── pencil-design.md
@@ -284,6 +291,7 @@ project/
 - `page-map.md` 是实现页面和状态的真相源
 - `pencil-bindings.md` 是实现页面到 Pencil 页面绑定的真相源
 - 在 `redesign-from-code` 里，现有代码只是真相行为，不是真相布局
+- 在 `overhaul-from-code` 里，现有代码是参考基线和迁移约束，不是新系统天然的最终行为真相
 - 复杂页面在 Pencil 重设计前应该先拆成 subpage、state、overlay 和 implementation surface
 - `design-registry.md` 里登记的首选 `.pen` 路径属于工作流自动维护的状态，不应该依赖用户手工填写
 - 一旦进入 Pencil 设计，Da Vinci 应该使用或创建这个项目内 `.pen` 路径，而不是继续沿用当前随手打开的 Pencil 文档
@@ -474,6 +482,12 @@ $da-vinci use greenfield-brainstorm to turn several product ideas into a page ma
 $da-vinci use redesign-from-code to inventory the existing app, identify current pages, and generate a new Pencil-backed UI plan
 ```
 
+### Overhaul from code
+
+```text
+$da-vinci use overhaul-from-code to inventory the current product, define preserve/revise/retire boundaries, rewrite the target flows and specs, and generate a Pencil-backed overhaul plan
+```
+
 ### Feature change
 
 ```text
@@ -499,14 +513,26 @@ Use the existing Da Vinci artifacts.
 Continue into full-delivery.
 ```
 
+### 大改版场景继续推进
+
+```text
+$da-vinci use continue for this existing overhaul-from-code workflow.
+
+Use the existing Da Vinci artifacts.
+Continue from proposal, migration-contract, and target specs into design or implementation.
+```
+
 ## 文档导航
 
 英文文档：
 
 - `docs/codex-natural-language-usage.md`
+- `docs/dv-command-reference.md`
 - `docs/prompt-entrypoints.md`
 - `docs/prompt-presets/`
   - 每个场景文件都包含 `Simple redesign`、`Complex redesign`、`Design-only`、`Continue`
+- `docs/workflow-overview.md`
+- `docs/pencil-rendering-workflow.md`
 - `docs/visual-adapters.md`
 - `docs/visual-assist-presets/`
 - `docs/workflow-examples.md`
@@ -516,8 +542,11 @@ Continue into full-delivery.
 中文文档：
 
 - `README.zh-CN.md`
+- `docs/zh-CN/dv-command-reference.md`
 - `docs/zh-CN/prompt-presets/`
   - 每个场景文件也都包含 `Simple redesign`、`Complex redesign`、`Design-only`、`Continue`
+- `docs/zh-CN/workflow-overview.md`
+- `docs/zh-CN/pencil-rendering-workflow.md`
 - `docs/zh-CN/visual-adapters.md`
 - `docs/zh-CN/visual-assist-presets/`
 - `docs/zh-CN/`

package/SKILL.md

@@ -16,6 +16,7 @@ Keep these rules fixed:
 - Tasks decide implementation order.
 - Code must follow both requirements and Pencil data.
 - Existing code is behavior truth, not layout truth, during `redesign-from-code`.
+- Existing code is reference evidence and migration baseline, not default final behavior truth, during `overhaul-from-code`.
 - When requirements and Pencil drift apart, stop and update the source artifacts before continuing implementation.
 
 ## Execution Policy
@@ -75,6 +76,25 @@ Do not stop merely because:
 
 Those are warnings unless they prevent safe implementation of the current in-scope work.
 
+## Next-Step Recommendation Discipline
+
+When Da Vinci reports a "next recommended step" or offers route suggestions, make the recommendation stateful rather than listing every possible command as if they were equally valid.
+
+Use this order:
+
+- if discovery or design-source artifacts are still missing, recommend the missing discovery or design work first
+- if design is still blocking, recommend `design`
+- if design is ready enough for implementation planning but `.da-vinci/changes/<change-id>/tasks.md` does not exist yet, recommend `tasks`
+- if `tasks.md` exists and `task checkpoint` is at least `PASS` or an explicitly accepted `WARN`, recommend `build`
+- if implementation is already underway or complete enough to check drift, recommend `verify`
+
+Hard rules:
+
+- do not present `build` as a co-equal next step when `tasks.md` does not exist yet
+- do not present `build` as the primary next step immediately after design completion unless task generation is already done and implementation readiness is clear
+- if design is complete but more in-scope surfaces still need design work, `design` may remain an optional branch, but `tasks` stays the primary next step before `build`
+- if multiple commands are shown, clearly mark only one as the primary next step for the current workflow state
+
 ## Invocation Model
 
 Canonical workflow name is `da-vinci`.
@@ -134,7 +154,10 @@ Supported modes:
 3. `redesign-from-code`
    - use when an existing product already has code and the UI must be redesigned globally or broadly
 
-4. `feature-change`
+4. `overhaul-from-code`
+   - use when an existing product needs a broad system-level rewrite where flows, logic, information architecture, and UI may all change
+
+5. `feature-change`
    - use when an existing product needs a scoped requirement change, page addition, or page update
 
 If the user does not specify a mode:
@@ -142,6 +165,7 @@ If the user does not specify a mode:
 - choose `greenfield-spec` for new projects with clear requirements
 - choose `greenfield-brainstorm` for exploratory new product ideation
 - choose `redesign-from-code` for broad UI replacement on existing code
+- choose `overhaul-from-code` for broad existing-project rewrites where old code is no longer the full behavior truth
 - choose `feature-change` for incremental product work
 
 ## Design Input Collection
@@ -378,6 +402,12 @@ Use these minimum flows:
 
 For broad refreshes, treat `.da-vinci/changes/<change-id>/specs/` as a redesign-slice directory, not as a single-file location.
 
+### `overhaul-from-code`
+
+`.da-vinci/project-inventory` -> `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/migration-contract` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` -> `DA-VINCI` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/design-brief` -> `.da-vinci/changes/<change-id>/design` -> `.da-vinci/changes/<change-id>/pencil-design` -> `.da-vinci/changes/<change-id>/pencil-bindings` -> `.da-vinci/changes/<change-id>/tasks` -> `.da-vinci/changes/<change-id>/verification`
+
+For broad overhauls, treat `.da-vinci/changes/<change-id>/specs/` as an overhaul-slice directory and keep `migration-contract.md` singular for preserve/revise/retire decisions.
+
 ### `feature-change`
 
 `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` for affected pages -> `DA-VINCI` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/design` -> `.da-vinci/changes/<change-id>/pencil-design` delta -> `.da-vinci/changes/<change-id>/pencil-bindings` delta -> `.da-vinci/changes/<change-id>/tasks` -> `.da-vinci/changes/<change-id>/verification`
@@ -405,6 +435,15 @@ If the active mode is `redesign-from-code`:
 - default to fresh visual composition unless the user explicitly asks to preserve the current layout skeleton
 - partition specs by redesign slice when one oversized `ui-refresh` spec would hide important implementation boundaries
 
+If the active mode is `overhaul-from-code`:
+
+- inventory current routes, pages, modules, key flows, integrations, and permission boundaries before redefining the target product
+- treat existing code as reference evidence and migration baseline rather than default final behavior truth
+- classify current system areas into `preserve`, `revise`, `retire`, and `unknown` in `migration-contract.md`
+- stabilize new `proposal.md` and `specs/` before broad Pencil design or implementation
+- update `page-map.md` to reflect the new target page set, not only the old route tree
+- route verify failures back to `migration-contract.md`, `page-map.md`, or specs when overhaul truth is still unstable
+
 ## Spec Partitioning Rules
 
 Do not default to one oversized `ui-refresh` spec for broad redesign work.
@@ -438,6 +477,24 @@ One redesign spec is acceptable when the refresh is mostly cosmetic, narrow, or
 
 Do not split page-by-page unless the product is unusually fragmented. Prefer implementable redesign slices over raw page counts.
 
+For `overhaul-from-code`:
+
+- keep one overall `proposal.md`
+- keep one `migration-contract.md`
+- keep one project-level `DA-VINCI.md`
+- keep one project-level `project-inventory.md`
+- keep one project-level `design-registry.md`
+- keep one project-level `page-map.md`
+- split `specs/` by overhaul slice when the rewrite spans multiple implementation or migration boundaries
+
+Preferred overhaul slices:
+
+- `shell-and-navigation`
+- `core-flows`
+- `account-and-settings`
+- `legacy-migration`
+- `admin-or-restricted`
+
 ## Design Source Rules
 
 Use `design-registry.md` as the project-level inventory of `.pen` sources.
@@ -698,3 +755,4 @@ After meaningful work, report:
 5. blockers or drift
 
 Keep updates concise and operational.
+Make `next recommended step` follow the state rules above; do not list `build` next to `tasks` as if they were equivalent when task generation has not happened yet.

package/commands/claude/da-vinci.md

@@ -22,6 +22,7 @@ Notes:
 - Requirements decide behavior.
 - Pencil decides presentation.
 - Code must follow both.
+- After design but before `tasks.md` exists, prefer `/dv:tasks` as the next route; treat `/dv:build` as implementation-ready only.
 - If `Visual Assist` is configured, resolve and state the actual primary visual adapter for this environment instead of assuming cross-platform skill equivalence.
 - Keep `.da-vinci/designs/` reserved for `.pen` files only.
 - On complex redesigns, design 1-3 anchor surfaces first and treat screenshot review as a binding gate before broad expansion.

package/commands/claude/dv/continue.md

@@ -21,4 +21,6 @@ Output should include:
 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
+- if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/dv:tasks`
+- only prefer `/dv:build` once task generation and implementation readiness are already clear
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine

package/commands/claude/dv/intake.md

@@ -24,3 +24,5 @@ Output should include:
 Route discipline:
 - do not default the user into `/dv:build`
 - `intake` should usually produce a main workflow prompt, not a build-only prompt
+- prefer `redesign-from-code`, `overhaul-from-code`, or `feature-change` when the request starts from an existing project
+- prefer `overhaul-from-code` when an existing project is redefining flows or logic rather than only replacing UI

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

@@ -21,6 +21,7 @@ Available routes:
 
 Important:
 - Treat `/prompts:*` as action selectors in Codex.
+- After design but before `tasks.md` exists, prefer `/prompts:dv-tasks` as the next route; treat `/prompts:dv-build` as implementation-ready only.
 - If `Visual Assist` is configured, resolve and state the actual primary visual adapter for this environment instead of assuming cross-platform skill equivalence.
 - Keep `.da-vinci/designs/` reserved for `.pen` files only.
 - On complex redesigns, design 1-3 anchor surfaces first and treat screenshot review as a binding gate before broad expansion.

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

@@ -21,4 +21,6 @@ Output should include:
 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
+- if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/prompts:dv-tasks`
+- only prefer `/prompts:dv-build` once task generation and implementation readiness are already clear
 - 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

@@ -24,4 +24,5 @@ Output should include:
 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
+- prefer `redesign-from-code`, `overhaul-from-code`, or `feature-change` when the request starts from an existing project
+- prefer `overhaul-from-code` when an existing project is redefining flows or logic rather than only replacing UI

package/commands/gemini/da-vinci.toml

@@ -24,6 +24,7 @@ Notes:
 - Requirements decide behavior.
 - Pencil decides presentation.
 - Code must follow both.
+- After design but before `tasks.md` exists, prefer `/dv:tasks` as the next route; treat `/dv:build` as implementation-ready only.
 - If `Visual Assist` is configured, resolve and state the actual primary visual adapter for this environment instead of assuming cross-platform skill equivalence.
 - Keep `.da-vinci/designs/` reserved for `.pen` files only.
 - On complex redesigns, design 1-3 anchor surfaces first and treat screenshot review as a binding gate before broad expansion.

package/commands/gemini/dv/continue.toml

@@ -20,5 +20,7 @@ Output should include:
 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
+- if design artifacts exist but `tasks.md` does not, prefer a continuation prompt that moves into `/dv:tasks`
+- only prefer `/dv:build` once task generation and implementation readiness are already clear
 - continuation prompts should usually target the main workflow entry so Da Vinci can resume the full state machine
 """

package/commands/gemini/dv/intake.toml

@@ -23,4 +23,6 @@ Output should include:
 Route discipline:
 - do not default the user into `/dv:build`
 - `intake` should usually produce a main workflow prompt, not a build-only prompt
+- prefer `redesign-from-code`, `overhaul-from-code`, or `feature-change` when the request starts from an existing project
+- prefer `overhaul-from-code` when an existing project is redefining flows or logic rather than only replacing UI
 """

package/docs/codex-natural-language-usage.md

@@ -65,6 +65,7 @@ Supported modes:
 - `greenfield-spec`
 - `greenfield-brainstorm`
 - `redesign-from-code`
+- `overhaul-from-code`
 - `feature-change`
 
 ## Scenario Recipes
@@ -104,6 +105,12 @@ $da-vinci use redesign-from-code to inventory the current product, preserve exis
 $da-vinci use feature-change to add or update one scoped feature, generate any required Pencil design delta, and implement the change safely.
 ```
 
+### 5. Existing product with a large overhaul
+
+```text
+$da-vinci use overhaul-from-code to inventory the current product, define preserve/revise/retire boundaries, rewrite the target flows and specs, and then generate Pencil-backed design work and implementation tasks.
+```
+
 ### 5. Existing Android project with global UI replacement
 
 ```text
@@ -175,4 +182,5 @@ Prefer:
 
 - `use intake` for unclear starts
 - `use redesign-from-code` for broad UI replacement
+- `use overhaul-from-code` for broad existing-product rewrites where new specs replace old behavior truth
 - `use feature-change` for narrow existing-product work