@xenonbyte/da-vinci-workflow 0.1.16 → 0.1.18

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

package/docs/dv-command-reference.md

@@ -0,0 +1,401 @@
+# `dv:` Command Reference
+
+This document explains the `dv:` routes as an operational state machine rather than a flat menu.
+
+Use it when you need to know:
+
+- what each `dv:` route does
+- when each route should be the primary next step
+- how the routes connect in normal delivery
+- what to do when `verify` finds drift
+
+Use [workflow-overview.md](/Users/xubo/x-skills/da-vinci/docs/workflow-overview.md) for the full end-to-end workflow and [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/pencil-rendering-workflow.md) for the dedicated Pencil rendering lifecycle.
+
+## Core Idea
+
+The `dv:` routes are not meant to be equally likely next steps at every moment.
+
+Da Vinci expects route recommendations to follow workflow state.
+
+Default progression:
+
+1. `breakdown`
+2. `design`
+3. `tasks`
+4. `build`
+5. `verify`
+
+Entry helpers:
+
+- `intake`
+- `prompt`
+- `continue`
+
+These helpers exist to select or resume the correct route. They are not substitutes for the main state machine.
+
+## Route Meanings
+
+### `/dv:intake`
+
+Use when:
+
+- the project situation is complex
+- the user does not know how to phrase the first workflow request
+- there are multiple truth sources
+
+Outputs:
+
+- recommended mode
+- recommended delivery intent
+- one executable first prompt
+- one conservative alternative when useful
+- one continuation prompt when useful
+
+### `/dv:prompt`
+
+Use when:
+
+- the scenario is already understood
+- the user wants prompt text directly
+
+Outputs:
+
+- one or more copy-ready prompts
+
+### `/dv:continue`
+
+Use when:
+
+- `DA-VINCI.md` or `.da-vinci/` artifacts already exist
+- the workflow paused and must resume
+
+Outputs:
+
+- detected workflow state
+- missing or weak artifacts
+- one primary continuation prompt
+- one conservative continuation prompt when useful
+
+Important continuation rule:
+
+- if design exists but `tasks.md` does not, continuation should usually point to `tasks`
+- it should not promote `build` as a co-equal next step yet
+
+### `/dv:breakdown`
+
+Use when:
+
+- scope, flows, states, or requirements still need to be stabilized
+
+Creates or updates:
+
+- `proposal.md`
+- `specs/<capability>/spec.md`
+
+For `overhaul-from-code`, this stage may also create:
+
+- `migration-contract.md`
+
+This is the behavior-truth shaping stage.
+
+### `/dv:design`
+
+Use when:
+
+- requirements are stable enough to design from
+- Pencil-backed design work must begin or continue
+- more anchor surfaces, states, overlays, or design variants still need to be rendered
+
+Creates or updates:
+
+- `design.md`
+- `pencil-design.md`
+
+This stage includes:
+
+- anchor-first design
+- screenshot review
+- layout hygiene
+- `.pen` persistence
+- design checkpoint
+- design-source checkpoint
+
+### `/dv:tasks`
+
+Use when:
+
+- design is ready enough to drive implementation planning
+- requirements plus Pencil coverage should be turned into ordered task groups
+
+Creates or updates:
+
+- `tasks.md`
+
+This is the implementation-planning stage.
+
+It does not write code.
+
+### `/dv:build`
+
+Use when:
+
+- requirements are implementation-safe
+- design and mapping are stable enough
+- `tasks.md` exists or implementation order is already clear
+
+Creates or updates:
+
+- application code
+- any artifacts that must be refreshed when drift is found
+
+This is the execution stage.
+
+### `/dv:verify`
+
+Use when:
+
+- you want to check requirement coverage
+- you want to check design coverage
+- you want to detect drift across requirements, Pencil, tasks, and code
+
+Creates or updates:
+
+- `verification.md`
+
+This is the truth-reconciliation stage.
+
+## State-Based Next-Step Rules
+
+These are the intended route recommendations.
+
+### After `/dv:design`
+
+If design is still blocking:
+
+- primary next step: `/dv:design`
+
+If design is healthy and `tasks.md` does not exist yet:
+
+- primary next step: `/dv:tasks`
+- optional: `/dv:design` if more in-scope surfaces still need design work
+- optional: `/dv:verify` if you want to check current requirement/design coverage before generating tasks
+
+Do not present `/dv:build` as a co-equal next step here.
+
+### After `/dv:tasks`
+
+If task quality is blocking:
+
+- primary next step: `/dv:tasks`
+
+If task checkpoint is healthy:
+
+- primary next step: `/dv:build`
+- optional: `/dv:verify` if you want to inspect requirement/design/task consistency before implementation starts
+
+### After `/dv:build`
+
+If implementation work remains:
+
+- primary next step: `/dv:build`
+
+If implementation is ready for drift checking:
+
+- primary next step: `/dv:verify`
+
+## Route Matrix
+
+| Current state | Primary next route | Secondary route |
+| --- | --- | --- |
+| Requirements unclear | `breakdown` | `intake` |
+| Requirements stable, design missing | `design` | `continue` |
+| Design unstable | `design` | `verify` |
+| Design stable, no `tasks.md` | `tasks` | `design` / `verify` |
+| Tasks unstable | `tasks` | `verify` |
+| Tasks stable, implementation-ready | `build` | `verify` |
+| Implementation underway | `build` | `verify` |
+| Implementation finished or drift suspected | `verify` | `build` |
+
+## `verify` Rollback Rules
+
+`verify` does not blindly send the workflow back one step.
+
+It should return the workflow to the truth layer that is wrong.
+
+### If `verify` finds design coverage gaps
+
+Examples:
+
+- missing pages
+- missing states
+- missing dialogs, sheets, or overlays
+- design disagrees with requirement scope
+
+Go back to:
+
+- `/dv:design`
+
+### If `verify` finds task decomposition gaps
+
+Examples:
+
+- missing implementation work
+- missing integration tasks
+- wrong dependency ordering
+- design coverage exists but tasks do not reflect it
+
+Go back to:
+
+- `/dv:tasks`
+
+### If `verify` finds implementation drift
+
+Examples:
+
+- code does not match Pencil layout or content structure
+- behavior does not match approved specs
+- task groups were not fully implemented
+
+Go back to:
+
+- `/dv:build`
+
+### If bindings still exist but the implementation page is missing
+
+Examples:
+
+- the canonical page is still present in `page-map.md`
+- `pencil-bindings.md` still points to a valid Pencil page
+- but the code page, route implementation, or UI module is missing
+
+Go back to:
+
+- `/dv:tasks` if implementation recovery still needs explicit planning
+- `/dv:build` if the rebuild path is already clear and the approved design still stands
+
+Do not discard the design binding only because the implementation disappeared.
+
+### If bindings still exist but the design source is missing
+
+Examples:
+
+- implementation code still exists
+- `pencil-bindings.md` still names a Pencil page
+- but the registered `.pen` source is gone, stale beyond reconciliation, or not traceable anymore
+
+Go back to:
+
+- `/dv:design`
+
+Reason:
+
+- this is a design-source failure, not just a coding gap
+- old code or exported PNGs are not enough to keep the binding healthy by themselves
+
+### If `verify` finds requirement-truth conflicts
+
+Examples:
+
+- proposal and spec disagree
+- implementation exceeded scope
+- code and spec conflict over behavior truth
+
+Go back to:
+
+- `/dv:breakdown`
+- or the main workflow entry via `continue` if several earlier artifacts need to be reconciled together
+
+### If `verify` finds overhaul-boundary conflicts
+
+Examples:
+
+- preserve / revise / retire decisions are inconsistent
+- old-system obligations and new target behavior are mixed together
+- page map still follows the legacy route tree instead of the approved target product
+- `DA-VINCI.md` or `design-brief.md` no longer matches the approved overhaul baseline
+
+Go back to:
+
+- `/dv:breakdown` when `proposal.md`, `migration-contract.md`, or specs are wrong
+- `/dv:design` when the target design or page structure drifted from the approved overhaul truth
+
+## Typical User Handling After `verify`
+
+If you are manually driving routes:
+
+1. run `/dv:verify`
+2. read which truth layer drifted
+3. execute the returned primary next route
+
+Quick fallback matrix:
+
+- binding exists, design healthy, code missing -> `/dv:tasks` or `/dv:build`
+- binding exists, code healthy, design source missing -> `/dv:design`
+
+If you do not want to decide manually:
+
+1. run `/dv:continue`
+2. let Da Vinci inspect the current artifacts
+3. follow the continuation prompt it generates
+
+## Recommended 0-to-1 Flow
+
+For a typical new product or large redesign:
+
+1. `/dv:intake` when the request is still messy
+2. `/dv:breakdown`
+3. `/dv:design`
+4. `/dv:tasks`
+5. `/dv:build`
+6. `/dv:verify`
+
+## Recommended Resume Flow
+
+When artifacts already exist:
+
+1. `/dv:continue`
+2. let it detect whether the next stage is:
+   - `design`
+   - `tasks`
+   - `build`
+   - `verify`
+
+## Flow Diagram
+
+```mermaid
+flowchart TD
+    A[intake or continue] --> B[breakdown]
+    B --> C[design]
+    C --> D{Design checkpoint healthy?}
+    D -- No --> C
+    D -- Yes --> E{tasks.md exists?}
+    E -- No --> F[tasks]
+    E -- Yes --> G[build]
+    F --> H{Task checkpoint healthy?}
+    H -- No --> F
+    H -- Yes --> G
+    G --> I[verify]
+    I --> J{Drift found?}
+    J -- No --> K[done]
+    J -- Design drift --> C
+    J -- Task drift --> F
+    J -- Code drift --> G
+    J -- Requirement drift --> B
+    J -- Overhaul boundary drift --> B
+```
+
+## Verify Rollback Diagram
+
+```mermaid
+flowchart TD
+    A[verify] --> B{Which truth layer failed?}
+    B -- Requirement or scope truth --> C[breakdown]
+    B -- Design truth --> D[design]
+    B -- Task truth --> E[tasks]
+    B -- Code truth --> F[build]
+    B -- Overhaul boundary truth --> C
+    C --> G[re-run verify later]
+    D --> G
+    E --> G
+    F --> G
+```

package/docs/mode-use-cases.md

@@ -61,7 +61,12 @@ Choose the mode by project start condition:
    - current codebase is the behavior source of truth
    - UI needs broad or global redesign
 
-4. `feature-change`
+4. `overhaul-from-code`
+   - project already exists
+   - current code is still migration evidence
+   - flows, logic, information architecture, or UI are being broadly redefined
+
+5. `feature-change`
    - project already exists
    - a scoped feature, page, or flow needs to be added or updated
 
@@ -138,8 +143,8 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 
 8. create `pencil-design.md`
    - record the generated Pencil screens
-   - if no registered project-local `.pen` exists yet, persist the first approved MCP snapshot into the registered `.pen` path under `.da-vinci/designs/`
-   - if a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits
+   - prefer `da-vinci pencil-session begin` before the first Pencil edit so the registered `.pen` is seeded and locked up front
+   - if a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current live MCP snapshot through `da-vinci pencil-session persist` after material live edits
    - keep screenshot exports under `.da-vinci/changes/<change-id>/exports/` rather than `.da-vinci/designs/`
 
 9. create `pencil-bindings.md`
@@ -468,7 +473,88 @@ Use this mode whenever the project already exists and the real work starts from
 
 ---
 
-## 4. `feature-change`
+## 4. `overhaul-from-code`
+
+### Typical scenario
+
+The product already exists, but this is not only a visual refresh.
+
+You may be:
+
+- redefining major flows
+- replacing parts of the logic model
+- resetting information architecture
+- preserving some integrations or constraints while retiring other legacy behavior
+
+### Example case
+
+Project:
+
+- existing B2B desktop product with legacy shell, permissions, and integrations
+
+Goal:
+
+- preserve selected integrations and data contracts
+- retire part of the old workflow
+- replace navigation, flows, and UI around a new operating model
+
+### Recommended request
+
+```text
+$da-vinci use overhaul-from-code to overhaul this existing product.
+Treat current code as migration evidence and reference baseline, not automatic final behavior truth.
+Inventory the current system, define preserve/revise/retire/unknown boundaries, rewrite the target flows and specs, then generate Pencil-backed design work and implementation tasks.
+```
+
+### What Da Vinci should do
+
+1. create `project-inventory.md`
+   - inventory routes
+   - inventory key flows
+   - inventory integrations, permissions, and legacy constraints
+
+2. create `proposal.md`
+   - define the target product direction
+   - define scope and non-goals
+
+3. create `migration-contract.md`
+   - classify `preserve`
+   - classify `revise`
+   - classify `retire`
+   - classify `unknown`
+
+4. create `specs/<slice>/spec.md`
+   - write the new target behavior truth
+   - split overhaul work by implementation or migration slice
+
+5. create or rebuild `page-map.md`
+   - define the target page set
+   - do not merely inherit the old route tree
+
+6. continue into:
+   - `DA-VINCI.md`
+   - `design-registry.md`
+   - `design-brief.md`
+   - `design.md`
+   - `pencil-design.md`
+   - `pencil-bindings.md`
+   - `tasks.md`
+   - `verification.md`
+
+### Where this mode differs from `redesign-from-code`
+
+- `redesign-from-code` keeps old code as behavior truth
+- `overhaul-from-code` treats old code as reference baseline and migration context
+- `redesign-from-code` is mainly for broad UI replacement
+- `overhaul-from-code` is for broad product rewrites on top of an existing system
+
+### Best fit
+
+Use this mode when the product already exists, but the new version must be defined through new specs rather than inherited automatically from the current code.
+
+---
+
+## 5. `feature-change`
 
 ### Typical scenario
 
@@ -610,6 +696,12 @@ $da-vinci use greenfield-brainstorm to synthesize the product idea, establish th
 $da-vinci use redesign-from-code to inventory the current product, establish or update DA-VINCI.md, generate a Pencil-backed redesign baseline, and prepare implementation tasks.
 ```
 
+### Existing project system-level overhaul
+
+```text
+$da-vinci use overhaul-from-code to inventory the current product, define migration boundaries, replace the target flows and specs, generate Pencil-backed overhaul pages, and prepare implementation tasks.
+```
+
 ### Existing project scoped feature
 
 ```text