@xenonbyte/da-vinci-workflow 0.1.3 → 0.1.4

package/README.md

@@ -27,11 +27,12 @@ This workflow is intended for:
 
 Current npm release target:
 
-- `@xenonbyte/da-vinci-workflow@0.1.3`
+- `@xenonbyte/da-vinci-workflow@0.1.4`
 
 Release highlights:
 
 - project-level visual contract support through `DA-VINCI.md`
+- redesign-from-code now prefers redesign-slice specs over one oversized `ui-refresh/spec.md`
 - Node-first install, uninstall, status, and asset validation commands
 - repo-local forward-test example for a `greenfield-spec` workflow
 
@@ -75,19 +76,19 @@ Da Vinci runs in this order:
 
 Depending on the mode, the workflow may use these artifacts:
 
-- `brainstorm.md`
-- `project-inventory.md`
+- `.da-vinci/changes/<change-id>/brainstorm.md`
+- `.da-vinci/project-inventory.md`
 - `DA-VINCI.md`
-- `design-brief.md`
-- `design-registry.md`
-- `page-map.md`
-- `proposal.md`
-- `specs/<capability>/spec.md`
-- `design.md`
-- `pencil-design.md`
-- `pencil-bindings.md`
-- `tasks.md`
-- `verification.md`
+- `.da-vinci/changes/<change-id>/design-brief.md`
+- `.da-vinci/design-registry.md`
+- `.da-vinci/page-map.md`
+- `.da-vinci/changes/<change-id>/proposal.md`
+- `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
+- `.da-vinci/changes/<change-id>/design.md`
+- `.da-vinci/changes/<change-id>/pencil-design.md`
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`
+- `.da-vinci/changes/<change-id>/tasks.md`
+- `.da-vinci/changes/<change-id>/verification.md`
 
 ### Artifact intent
 
@@ -105,6 +106,44 @@ Depending on the mode, the workflow may use these artifacts:
 - `tasks.md`: implementation order and task groups
 - `verification.md`: requirement coverage, design coverage, and drift findings
 
+### Spec granularity rule
+
+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`.
+
+## Artifact placement
+
+Recommended project layout:
+
+```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
+```
+
+Placement rules:
+
+- keep `DA-VINCI.md` at the project root
+- keep project-wide workflow files in `.da-vinci/`
+- 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
+
 ## Checkpoints
 
 Da Vinci uses these checkpoints:
@@ -297,6 +336,7 @@ $da-vinci use feature-change to add a billing page, generate the relevant Pencil
 See:
 
 - `docs/workflow-examples.md`
+- `docs/mode-use-cases.md`
 
 ## Repository layout
 

package/SKILL.md

@@ -27,6 +27,15 @@ That means:
 - treat checkpoints as internal execution guards, not approval steps
 - stop only when a true blocking condition exists
 
+Treat execution intent as `full-delivery` by default when the user asks to:
+
+- complete development
+- implement the generated design
+- redesign the whole product UI
+- finish the project or finish the refresh
+
+Do not stop at `tasks.md` in those cases.
+
 Continue automatically through:
 
 - mode selection
@@ -41,6 +50,14 @@ Continue automatically through:
 - implementation
 - verification
 
+If `tasks.md` exists and the active request is `full-delivery`:
+
+- treat `task checkpoint` as the handoff into implementation, not as an end state
+- start Task Group 1 automatically after a `PASS`
+- start Task Group 1 automatically after a `WARN` unless the warning changes the truth of behavior, source mapping, or permissions
+- do not emit "next recommended step: start Task Group 1" as a terminal outcome
+- instead continue into code changes and report progress by task group
+
 Stop and ask only when:
 
 - the user explicitly interrupts
@@ -49,6 +66,14 @@ Stop and ask only when:
 - source artifacts conflict badly enough that continuing would guess the truth
 - a destructive action would change the project baseline significantly
 
+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
+
+Those are warnings unless they prevent safe implementation of the current in-scope work.
+
 ## Invocation Model
 
 Canonical workflow name is `da-vinci`.
@@ -135,6 +160,12 @@ Run the workflow in this order:
 10. Implement code from requirements plus Pencil data
 11. Verify behavior drift and design drift before closing the change
 
+Default completion rule:
+
+- if the request is `plan-only`, stop after planning artifacts
+- if the request is `design-only`, stop after design artifacts and bindings
+- otherwise assume `full-delivery` and continue through implementation and verification
+
 ## Load References On Demand
 
 Load only the reference that matches the current step:
@@ -151,19 +182,19 @@ Load only the reference that matches the current step:
 
 Use these artifacts unless the project defines a different schema:
 
-1. `brainstorm.md`
-2. `project-inventory.md`
+1. `.da-vinci/changes/<change-id>/brainstorm.md`
+2. `.da-vinci/project-inventory.md`
 3. `DA-VINCI.md`
-4. `design-brief.md`
-5. `design-registry.md`
-6. `page-map.md`
-7. `proposal.md`
-8. `specs/<capability>/spec.md`
-9. `design.md`
-10. `pencil-design.md`
-11. `pencil-bindings.md`
-12. `tasks.md`
-13. `verification.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`
 
 Not every mode requires every artifact.
 
@@ -198,25 +229,59 @@ Optional artifacts:
 - `tasks.md`: implementation order and deliverable task groups
 - `verification.md`: requirement coverage, Pencil coverage, and drift findings
 
+## Artifact Placement
+
+Use this placement model inside the target project:
+
+### Project root
+
+- `DA-VINCI.md`
+
+Keep this file at the project root so the visual contract is easy to discover and reuse.
+
+### Project-level workflow directory
+
+- `.da-vinci/project-inventory.md`
+- `.da-vinci/design-registry.md`
+- `.da-vinci/page-map.md`
+
+These files describe project-wide facts that can outlive any one change.
+
+### Change-level workflow directory
+
+- `.da-vinci/changes/<change-id>/brainstorm.md`
+- `.da-vinci/changes/<change-id>/design-brief.md`
+- `.da-vinci/changes/<change-id>/proposal.md`
+- `.da-vinci/changes/<change-id>/design.md`
+- `.da-vinci/changes/<change-id>/pencil-design.md`
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`
+- `.da-vinci/changes/<change-id>/tasks.md`
+- `.da-vinci/changes/<change-id>/verification.md`
+- `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
+
+These files belong to one concrete delivery effort and should not clutter the project root.
+
 ## Mode-Specific Artifact Flow
 
 Use these minimum flows:
 
 ### `greenfield-spec`
 
-`DA-VINCI` -> `design-brief` -> `proposal` -> `specs` -> `page-map` -> `design-registry` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
+`DA-VINCI` -> `.da-vinci/changes/<change-id>/design-brief` -> `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` -> `.da-vinci/design-registry` -> `.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`
 
 ### `greenfield-brainstorm`
 
-`brainstorm` -> `DA-VINCI` -> `design-brief` -> `proposal` -> `specs` -> `page-map` -> `design-registry` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
+`.da-vinci/changes/<change-id>/brainstorm` -> `DA-VINCI` -> `.da-vinci/changes/<change-id>/design-brief` -> `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` -> `.da-vinci/design-registry` -> `.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`
 
 ### `redesign-from-code`
 
-`project-inventory` -> `DA-VINCI` -> `design-registry` -> `proposal` -> `specs` -> `page-map` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
+`.da-vinci/project-inventory` -> `DA-VINCI` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` -> `.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 refreshes, treat `.da-vinci/changes/<change-id>/specs/` as a redesign-slice directory, not as a single-file location.
 
 ### `feature-change`
 
-`proposal` -> `specs` -> `page-map` for affected pages -> `DA-VINCI` -> `design-registry` -> `design` -> `pencil-design` delta -> `pencil-bindings` delta -> `tasks` -> `verification`
+`.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`
 
 ## Requirement Breakdown Rules
 
@@ -237,6 +302,40 @@ If the active mode is `redesign-from-code`:
 
 - inventory current routes, pages, and modules before redefining page structure
 - distinguish preserved behavior from replaced presentation
+- partition specs by redesign slice when one oversized `ui-refresh` spec would hide important implementation boundaries
+
+## Spec Partitioning Rules
+
+Do not default to one oversized `ui-refresh` spec for broad redesign work.
+
+For `redesign-from-code`:
+
+- keep one overall `proposal.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 redesign slice when the refresh is broad
+
+Preferred redesign slices:
+
+- `shared-shell`
+- `core-pages`
+- `settings-and-secondary`
+- `admin-or-restricted`
+- `reference-gap-pages`
+
+Split broad redesign work into multiple spec slices when one or more of these are true:
+
+- the refresh covers more than five canonical pages
+- the refresh spans more than two top-level route groups or page families
+- the redesign includes both shared-shell changes and page-content changes
+- prior HTML or Pencil references cover only part of the product surface
+- different page groups carry different layout, density, or access constraints
+
+One redesign spec is acceptable when the refresh is mostly cosmetic, narrow, or limited to a small product surface.
+
+Do not split page-by-page unless the product is unusually fragmented. Prefer implementable redesign slices over raw page counts.
 
 ## Design Source Rules
 

package/docs/mode-use-cases.md

@@ -0,0 +1,540 @@
+# Da Vinci Mode Use Cases
+
+This document shows how to use Da Vinci in each workflow mode with concrete project scenarios.
+
+Use it when you need to decide:
+
+- which mode fits the current job
+- what inputs to provide first
+- which artifacts Da Vinci should create
+- how `DA-VINCI.md`, Pencil, and implementation should interact
+
+## Recommended output layout inside a project
+
+Use this output structure:
+
+```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
+```
+
+Rule:
+
+- only `DA-VINCI.md` belongs at the project root
+- all other workflow outputs should stay under `.da-vinci/`
+
+## Quick mode selection
+
+Choose the mode by project start condition:
+
+1. `greenfield-spec`
+   - new project
+   - requirements are already clear enough to write specs
+
+2. `greenfield-brainstorm`
+   - new project
+   - requirements are still spread across multiple rounds of ideation
+
+3. `redesign-from-code`
+   - project already exists
+   - current codebase is the behavior source of truth
+   - UI needs broad or global redesign
+
+4. `feature-change`
+   - project already exists
+   - a scoped feature, page, or flow needs to be added or updated
+
+---
+
+## 1. `greenfield-spec`
+
+### Typical scenario
+
+You are starting a new desktop or web product. The product scope is already clear enough to write requirements. You want Da Vinci to:
+
+1. break requirements into pages and flows
+2. establish a visual baseline
+3. generate Pencil-backed pages
+4. create implementation tasks
+5. build from requirement plus Pencil data
+
+### Example case
+
+Project:
+
+- desktop software for annotated design delivery
+
+Known inputs:
+
+- the product converts HTML and Figma sources into annotated design output
+- the output is also exposed as MCP-ready structured data
+- launch needs a homepage and a product detail page
+
+### Recommended request
+
+```text
+$da-vinci use greenfield-spec to break down a new desktop software product for annotated design delivery.
+Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bindings, and implementation tasks.
+```
+
+### What Da Vinci should do
+
+1. create `DA-VINCI.md`
+   - choose or infer a stable visual contract
+   - record theme, palette, typography direction, and component tone
+
+2. create `design-brief.md`
+   - confirm form factor and page-level design priorities
+
+3. create `proposal.md`
+   - define scope, non-goals, and success criteria
+
+4. create `specs/<capability>/spec.md`
+   - define behavior, states, acceptance, and edge cases
+
+5. create `page-map.md`
+   - define the canonical pages and page responsibilities
+
+6. create `design-registry.md`
+   - register the active `.pen` source once Pencil work starts
+
+7. create `design.md`
+   - define page structure and layout strategy
+
+8. create `pencil-design.md`
+   - record the generated Pencil screens
+
+9. create `pencil-bindings.md`
+   - map implementation pages to Pencil pages
+
+10. create `tasks.md`
+   - define implementation order
+
+11. build code from:
+   - requirements
+   - `DA-VINCI.md`
+   - Pencil page data
+
+### What should be true before implementation
+
+- `DA-VINCI.md` exists and is stable
+- every core page exists in `page-map.md`
+- every implementation page has a Pencil counterpart or an explicit exception
+- `task checkpoint` passes
+
+### Best fit
+
+Use this mode when you do **not** need idea synthesis first and when the product scope is not primarily reverse-engineered from an existing codebase.
+
+---
+
+## 2. `greenfield-brainstorm`
+
+### Typical scenario
+
+You are starting a new project, but the inputs are still rough. The user may have described:
+
+- several possible features
+- multiple product directions
+- unclear page boundaries
+- conflicting style preferences
+
+The goal is to turn those messy inputs into a buildable workflow.
+
+### Example case
+
+Project:
+
+- AI writing workspace for product teams
+
+User inputs across several rounds:
+
+- “Need a docs editor”
+- “Also maybe an AI copilot”
+- “Maybe a dashboard”
+- “Should feel professional, not playful”
+- “Could be a web app or maybe a desktop tool”
+
+### Recommended request
+
+```text
+$da-vinci use greenfield-brainstorm to turn product brainstorming into a stable delivery workflow.
+First synthesize the product direction, then generate DA-VINCI.md, specs, page map, Pencil-backed pages, and implementation tasks.
+```
+
+### What Da Vinci should do
+
+1. create `brainstorm.md`
+   - collect recurring themes
+   - separate stable goals from open questions
+   - identify contradictions
+
+2. create or infer `DA-VINCI.md`
+   - once visual preferences are stable enough
+   - do not generate many unrelated pages before this exists
+
+3. create `design-brief.md`
+   - record form factor and design direction
+
+4. create `proposal.md`
+   - stabilize scope
+
+5. create `specs/<capability>/spec.md`
+   - convert brainstorm into testable behavior
+
+6. create `page-map.md`
+   - define real pages instead of vague product areas
+
+7. continue with:
+   - `design-registry.md`
+   - `design.md`
+   - `pencil-design.md`
+   - `pencil-bindings.md`
+   - `tasks.md`
+
+### Where this mode differs from `greenfield-spec`
+
+The extra work is at the front:
+
+- synthesize first
+- design later
+- code only after the idea set is stable enough
+
+### Common blockers
+
+- product surface is still unclear: web app vs desktop app
+- core user flow is still contradictory
+- design preference is unstable enough that `DA-VINCI.md` would be noise instead of a baseline
+
+### Best fit
+
+Use this mode when the biggest risk is not implementation, but ambiguity.
+
+---
+
+## 3. `redesign-from-code`
+
+### Typical scenario
+
+You already have a working project. You want to redesign all or most of the UI while preserving behavior and routes.
+
+This is the right mode for:
+
+- full visual refresh
+- broad UI cleanup
+- migration from old interface style to a new product language
+- redesign using existing design references
+
+### Example case A: redesign from current code only
+
+Project:
+
+- existing SaaS admin app
+
+Goal:
+
+- keep all routes and behavior
+- replace the visual system with a dark, dense, desktop-tool style
+
+Recommended request:
+
+```text
+$da-vinci use redesign-from-code to redesign the whole product UI.
+Keep current routes and behavior, inventory the existing pages and shared layouts, create DA-VINCI.md as the visual contract, generate a Pencil-backed design baseline, bind implementation pages to Pencil pages, and produce implementation tasks for a full UI refresh.
+```
+
+### Example case B: redesign from code plus existing design references
+
+Project:
+
+- existing product with some earlier design drafts
+
+Goal:
+
+- current code remains the behavior source of truth
+- existing design drafts become the visual reference source
+- missing pages should be designed to match the same style
+
+Recommended request:
+
+```text
+$da-vinci use redesign-from-code to redesign the whole product UI.
+Current code is the behavior source of truth. Existing design drafts are the visual reference source.
+Register the design sources, extract DA-VINCI.md from them, bind covered pages, generate Pencil designs for uncovered pages, and create implementation tasks.
+```
+
+### What Da Vinci should do
+
+1. create `project-inventory.md`
+   - inventory routes
+   - inventory pages
+   - inventory shared regions
+   - inventory current UI patterns
+
+2. detect or create `DA-VINCI.md`
+   - if prior design references exist, extract the baseline from them
+   - if not, infer the new visual contract from the redesign request
+
+3. create or update `design-registry.md`
+   - register old and new `.pen` sources
+
+4. create or update `page-map.md`
+   - identify canonical implementation pages
+
+5. create `design.md`
+   - define redesign layout strategy and component strategy
+
+6. create or update `pencil-design.md`
+   - build the new redesign baseline in Pencil
+
+7. create or update `pencil-bindings.md`
+   - bind pages to redesign screens
+
+8. create `tasks.md`
+   - group implementation by layout shell, shared components, and page slices
+
+9. continue directly into implementation when the request is a full redesign
+   - start Task Group 1 automatically
+   - preserve current behavior
+   - apply the redesign through code, not only through planning artifacts
+
+### Critical rule in this mode
+
+For redesign work:
+
+- current code decides behavior
+- `DA-VINCI.md` decides the new visual contract
+- Pencil decides page-by-page presentation
+
+### Spec partitioning rule
+
+For broad refreshes, do not keep everything inside one `ui-refresh/spec.md` unless the project surface is genuinely small or the change is mostly cosmetic.
+
+Preferred structure:
+
+- keep one overall `proposal.md`
+- keep one project-level `page-map.md`
+- split `specs/` by redesign slice
+
+Recommended redesign slices:
+
+- `shared-shell`
+- `core-pages`
+- `settings-and-secondary`
+- `admin-or-restricted`
+- `reference-gap-pages`
+
+This keeps implementation traceable without falling into one-spec-per-page fragmentation.
+
+### Important execution rule
+
+For a request like:
+
+- "redesign the whole product UI"
+- "globally update all UI"
+- "complete the refresh"
+
+Da Vinci should treat the intent as `full-delivery`.
+
+That means it should not stop after:
+
+- `design.md`
+- `pencil-design.md`
+- `pencil-bindings.md`
+- `tasks.md`
+
+Instead it should:
+
+1. generate the redesign artifacts
+2. run `task checkpoint`
+3. if the result is `PASS` or non-blocking `WARN`, immediately enter Task Group 1
+4. modify code while preserving current behavior
+5. use `execution checkpoint` only after implementation starts
+
+### Example: redesign from code plus HTML design references
+
+Project:
+
+- existing application with complete functional code
+- some HTML design drafts already exist
+- those HTML drafts are visual references and suggestions, not 1:1 restoration targets
+
+Recommended request:
+
+```text
+$da-vinci use redesign-from-code to redesign the whole product UI.
+Current code is the behavior source of truth.
+Existing HTML design drafts are visual references and suggestions, not restoration targets.
+Please inventory the current pages and shared layouts, register the HTML drafts as design references, extract DA-VINCI.md as the project visual contract, generate a unified Pencil design baseline, bind implementation pages to redesign screens, and continue implementation automatically unless a true blocker exists.
+```
+
+Expected behavior:
+
+1. inventory current pages and shared regions
+2. register the HTML drafts as design references
+3. extract a stable `DA-VINCI.md`
+4. split broad redesign work into multiple spec slices when needed
+5. create or refine Pencil redesign screens
+6. bind implementation pages to redesign screens
+7. generate `tasks.md` aligned to the redesign slices
+8. continue into code changes without stopping at "next recommended step"
+
+### Best fit
+
+Use this mode whenever the project already exists and the real work starts from discovery and redesign, not from a blank page.
+
+---
+
+## 4. `feature-change`
+
+### Typical scenario
+
+The product already exists. You do not want a whole redesign. You want a single change to flow through requirements, Pencil, and code.
+
+Examples:
+
+- add a billing page
+- redesign an onboarding flow
+- add a settings subsection
+- add a new dashboard tab
+
+### Example case
+
+Project:
+
+- existing product with current page system and visual contract
+
+Change:
+
+- add a billing center page and connect it to the existing settings area
+
+### Recommended request
+
+```text
+$da-vinci use feature-change to add a billing center page.
+Keep the current behavior and project style baseline, update the affected page map, generate the Pencil design delta, bind the new page, and create implementation tasks.
+```
+
+### What Da Vinci should do
+
+1. create or update `proposal.md`
+   - define the change scope
+
+2. create or update `specs/<capability>/spec.md`
+   - define the new behavior or updated behavior
+
+3. update `page-map.md`
+   - only for affected pages and related flows
+
+4. reuse `DA-VINCI.md`
+   - unless the change explicitly introduces a new product area or rebrand
+
+5. update `design-registry.md`
+   - if a new `.pen` source or screen is added
+
+6. create `pencil-design.md` delta
+   - only for the affected pages
+
+7. update `pencil-bindings.md`
+   - bind the new or changed page
+
+8. create `tasks.md`
+   - implementation order for the scoped change
+
+9. implement and verify
+
+### Why this mode matters
+
+Without a dedicated change mode, AI tends to:
+
+- redesign too much
+- regenerate pages that are out of scope
+- ignore the existing visual contract
+
+This mode prevents that.
+
+---
+
+## How `DA-VINCI.md` should behave in every mode
+
+`DA-VINCI.md` is not optional noise. It is the project-level visual contract.
+
+Use it like this:
+
+1. if it exists
+   - reuse it
+   - avoid asking duplicate style questions
+   - avoid page-by-page style reinvention
+
+2. if it does not exist
+   - generate it from stable user preference, existing code signals, or prior design sources
+   - save it before broad Pencil generation
+
+3. if the project is rebranding
+   - update `DA-VINCI.md`
+   - then propagate the new baseline through Pencil and implementation
+
+---
+
+## How to choose between design sources
+
+Use this source order:
+
+1. `DA-VINCI.md`
+   - project visual baseline
+
+2. `design-registry.md`
+   - which `.pen` sources are active
+
+3. `pencil-bindings.md`
+   - which page maps to which Pencil screen
+
+4. implementation code
+   - behavior truth for existing products
+
+5. user prompt
+   - high-level direction and scope
+
+---
+
+## Recommended request templates
+
+### New project with clear scope
+
+```text
+$da-vinci use greenfield-spec to turn this new product into requirements, Pencil-backed pages, and implementation tasks.
+```
+
+### New project from rough ideation
+
+```text
+$da-vinci use greenfield-brainstorm to synthesize the product idea, establish the visual baseline, and generate a buildable workflow.
+```
+
+### Existing project full redesign
+
+```text
+$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 scoped feature
+
+```text
+$da-vinci use feature-change to add or update a page while preserving the current project visual contract and behavior baseline.
+```

package/docs/workflow-examples.md

@@ -61,11 +61,11 @@ Expected flow:
 1. scan the existing product into `project-inventory.md`
 2. register any current `.pen` sources in `design-registry.md`
 3. define redesign scope in `proposal.md`
-4. write redesign constraints in `specs/<capability>/spec.md`
+4. split broad redesign work into `specs/<slice>/spec.md` files when one large `ui-refresh` spec would be too coarse
 5. rebuild or refine `page-map.md`
 6. create new or updated Pencil pages
 7. bind routes and pages to Pencil screens
-8. generate tasks
+8. generate tasks aligned to the redesign slices
 9. build and verify
 
 ## 4. `feature-change`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js"

package/references/artifact-templates.md

@@ -4,6 +4,37 @@ Use these templates as the default artifact shapes for Da Vinci.
 
 Keep headings stable unless the project requires a different schema.
 
+## Placement Rule
+
+Write artifacts into the target project using this rule:
+
+- keep `DA-VINCI.md` at the project root
+- keep project-level workflow files in `.da-vinci/`
+- keep change-level workflow files in `.da-vinci/changes/<change-id>/`
+
+Recommended placement:
+
+```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`
 
 Use this structure:
@@ -33,6 +64,10 @@ Use this structure:
 
 Use this artifact only when ideas are still being synthesized.
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/brainstorm.md`
+
 ## `project-inventory.md`
 
 Use this structure:
@@ -63,6 +98,10 @@ Use this structure:
 
 Use this artifact when redesign starts from an existing codebase.
 
+Recommended path:
+
+- `.da-vinci/project-inventory.md`
+
 ## `DA-VINCI.md`
 
 Use this structure:
@@ -121,6 +160,10 @@ Use this structure:
 
 Use this artifact as a project-level visual contract. Generate it when the project does not already have one.
 
+Recommended path:
+
+- `DA-VINCI.md`
+
 ## `design-brief.md`
 
 Use this structure:
@@ -156,6 +199,10 @@ Use this structure:
 
 Use this artifact whenever the project is new or the design direction is not obvious from the existing product.
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/design-brief.md`
+
 ## `design-registry.md`
 
 Use this structure:
@@ -182,6 +229,10 @@ Use this structure:
 
 Use this artifact whenever a project can have one or more Pencil sources.
 
+Recommended path:
+
+- `.da-vinci/design-registry.md`
+
 ## `page-map.md`
 
 Use this structure:
@@ -214,6 +265,10 @@ Use this structure:
 
 Use this artifact for every mode. It is the canonical page list.
 
+Recommended path:
+
+- `.da-vinci/page-map.md`
+
 ## `proposal.md`
 
 Use this structure:
@@ -249,6 +304,10 @@ Use this structure:
 - Observable outcomes
 ```
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/proposal.md`
+
 ## `specs/<capability>/spec.md`
 
 Use this structure:
@@ -287,6 +346,10 @@ Use this structure:
 
 Write behavior in direct, testable language.
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
+
 ## `design.md`
 
 Use this structure:
@@ -318,6 +381,10 @@ Use this structure:
 - Unresolved design decisions
 ```
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/design.md`
+
 ## `pencil-design.md`
 
 Use this structure:
@@ -348,6 +415,10 @@ Use this structure:
 - Important layout or styling constraints to preserve in code
 ```
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/pencil-design.md`
+
 ## `tasks.md`
 
 Use this structure:
@@ -374,6 +445,10 @@ Use this structure:
 
 Prefer top-level task groups. They are required for execution checkpoints.
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/tasks.md`
+
 ## `pencil-bindings.md`
 
 Use this structure:
@@ -397,6 +472,10 @@ Use this structure:
 
 Use this artifact whenever implementation must trace back to Pencil pages.
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`
+
 ## `verification.md`
 
 Use this structure:
@@ -420,3 +499,7 @@ Use this structure:
 - PASS / WARN / BLOCK
 - Next action
 ```
+
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/verification.md`

package/references/checkpoints.md

@@ -14,6 +14,11 @@ Default handling:
 
 Do not pause the workflow just because a checkpoint ran.
 
+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
+
 ## Visual Contract Rule
 
 Before broad Pencil page generation:
@@ -57,6 +62,7 @@ Check:
 - important states are present
 - acceptance conditions are testable
 - risky areas are called out early
+- redesign scope is not too broad for a single spec when the active mode is `redesign-from-code`
 
 Result meanings:
 
@@ -64,6 +70,13 @@ Result meanings:
 - `WARN`: continue, but update artifacts soon
 - `BLOCK`: update source artifacts before moving on
 
+Spec partitioning guidance for `redesign-from-code`:
+
+- one spec is acceptable for a small or mostly cosmetic refresh
+- one spec is too coarse when the redesign spans many pages, multiple route groups, both shared shell and page content, or uneven design-reference coverage
+- use `WARN` when the current spec is slightly too broad but tasks can still be corrected quickly
+- use `BLOCK` when the current spec is so broad that implementation would lose traceability across redesign slices
+
 ## `design checkpoint`
 
 Run after Pencil pages exist and before implementation tasks are locked.
@@ -112,13 +125,33 @@ Check:
 - tasks cover behavior from specs
 - tasks cover integration and verification work
 - tasks are ordered by dependency
+- top-level task groups map cleanly to the active spec slices when multiple redesign slices exist
 
 Result meanings:
 
-- `PASS`: safe to start implementation
-- `WARN`: implementation can start, but task quality is weak
+- `PASS`: safe to start implementation immediately
+- `WARN`: implementation can start immediately, but task quality is weak or follow-up artifact cleanup is still advisable
 - `BLOCK`: rewrite tasks before implementation
 
+Automatic continuation rule:
+
+- if the active intent is `full-delivery`, `PASS` must immediately continue into Task Group 1
+- if the active intent is `full-delivery`, `WARN` must still continue into Task Group 1 unless the warning creates behavior ambiguity, mapping ambiguity, missing permissions, or a destructive-baseline risk
+- only `BLOCK` is allowed to stop the workflow before implementation
+
+Examples of `WARN`, not `BLOCK`:
+
+- an additional follow-up spec may be needed for currently untouched behavior
+- some legacy or out-of-scope surfaces remain intentionally excluded
+- the active Pencil source should also be saved or exported for stronger repository traceability
+
+Examples of `BLOCK`:
+
+- the implementation would invent new behavior that has no spec support
+- page-to-Pencil bindings are too weak to know which redesign screen to follow
+- required permissions, environment access, or protected files are unavailable
+- the implementation would overwrite the project baseline in a destructive way without an explicit go-ahead
+
 ## `execution checkpoint`
 
 Run after each top-level task group during implementation.
@@ -136,6 +169,10 @@ Result meanings:
 - `WARN`: continue, but record the issue
 - `BLOCK`: update artifacts before continuing
 
+Do not downgrade `execution checkpoint` into a planning checkpoint.
+
+Its job is to keep code aligned after implementation starts, not to justify stopping before Task Group 1.
+
 ## Reporting Format
 
 Use this reporting shape:

package/references/modes.md

@@ -54,7 +54,7 @@ Entry artifacts:
 - `project-inventory.md`
 - `design-registry.md`
 - `proposal.md`
-- `specs/<capability>/spec.md`
+- `specs/<capability-or-slice>/spec.md`
 - `page-map.md`
 
 Best for:
@@ -63,6 +63,13 @@ Best for:
 - layout modernization
 - design-system replacement
 
+Spec guidance:
+
+- keep one overall `proposal.md`
+- keep one project-level `page-map.md`
+- split `specs/` by redesign slice when the refresh is broad
+- do not assume one `ui-refresh/spec.md` is enough for a large application
+
 ## `feature-change`
 
 Use when: