@xenonbyte/da-vinci-workflow 0.1.2 → 0.1.4

package/README.md

@@ -23,6 +23,19 @@ This workflow is intended for:
 - redesign from existing code
 - scoped feature delivery on an existing product
 
+## Current release
+
+Current npm release target:
+
+- `@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
+
 ## Supported workflow modes
 
 Da Vinci V2 supports four modes.
@@ -49,36 +62,39 @@ Da Vinci runs in this order:
 
 1. select the active mode
 2. build the correct source artifacts
-3. collect design inputs and register design sources
-4. define or discover the project page map
-5. create or update Pencil designs
-6. bind implementation pages to Pencil pages
-7. read Pencil design data through MCP
-8. generate implementation tasks
-9. implement code from requirements plus Pencil data
-10. verify requirement drift and design drift
+3. detect or generate `DA-VINCI.md` as the project visual contract
+4. collect design inputs and register design sources
+5. define or discover the project page map
+6. create or update Pencil designs
+7. bind implementation pages to Pencil pages
+8. read Pencil design data through MCP
+9. generate implementation tasks
+10. implement code from requirements plus Pencil data
+11. verify requirement drift and design drift
 
 ## Default artifacts
 
 Depending on the mode, the workflow may use these artifacts:
 
-- `brainstorm.md`
-- `project-inventory.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>/brainstorm.md`
+- `.da-vinci/project-inventory.md`
+- `DA-VINCI.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
 
 - `brainstorm.md`: raw ideas before specs are stable
 - `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
 - `design-registry.md`: project-level `.pen` source inventory
 - `page-map.md`: canonical page list and page responsibilities
@@ -90,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:
@@ -137,6 +191,7 @@ Da Vinci treats Pencil as a structured design source, not as a screenshot source
 
 Rules:
 
+- `DA-VINCI.md` is the project-level visual contract for cross-page consistency
 - `design-registry.md` is the project-level inventory of `.pen` sources
 - `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
@@ -158,6 +213,7 @@ When neither mappings nor usable design sources exist:
 
 Before generating Pencil designs for a greenfield project, Da Vinci should collect or infer:
 
+- whether `DA-VINCI.md` already exists
 - product form factor
 - visual tone
 - density
@@ -166,10 +222,16 @@ Before generating Pencil designs for a greenfield project, Da Vinci should colle
 
 Preferred inference order:
 
-1. existing artifacts
-2. project-local signals
-3. explicit user answers
-4. short clarification questions
+1. `DA-VINCI.md`
+2. existing artifacts
+3. project-local signals
+4. explicit user answers
+5. short clarification questions
+
+If `DA-VINCI.md` does not exist:
+
+- generate it from stable user preferences, existing project signals, or inferred defaults
+- save it before generating many project pages, so later pages do not drift stylistically
 
 ## Installation
 
@@ -274,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,9 +27,19 @@ 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
+- project visual-contract detection
 - requirement breakdown
 - page mapping
 - design input collection
@@ -40,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
@@ -48,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`.
@@ -85,6 +111,11 @@ If the user does not specify a mode:
 
 Before generating new Pencil designs for a greenfield project, collect or infer:
 
+0. project visual contract
+   - detect whether `DA-VINCI.md` already exists
+   - if it exists, treat it as the visual baseline for future pages
+   - if it does not exist, generate it from stable user preferences, existing project signals, or inferred defaults before broad Pencil page generation
+
 1. product form factor
    - desktop software
    - web app
@@ -105,10 +136,11 @@ Before generating new Pencil designs for a greenfield project, collect or infer:
 
 Use this priority order:
 
-1. existing workflow artifacts
-2. project-local config or project codebase signals
-3. explicit user answers
-4. short clarification questions
+1. `DA-VINCI.md`
+2. existing workflow artifacts
+3. project-local config or project codebase signals
+4. explicit user answers
+5. short clarification questions
 
 Do not repeatedly ask for inputs that are already stable in the artifacts.
 
@@ -118,14 +150,21 @@ Run the workflow in this order:
 
 1. Select the active mode
 2. Build the correct source artifacts for that mode
-3. Collect design inputs and register available design sources
-4. Define or discover the project page map
-5. Create or update Pencil designs for the required pages
-6. Bind implementation pages to Pencil pages
-7. Read Pencil design data through MCP
-8. Generate implementation tasks
-9. Implement code from requirements plus Pencil data
-10. Verify behavior drift and design drift before closing the change
+3. Detect or generate `DA-VINCI.md` as the project visual contract
+4. Collect design inputs and register available design sources
+5. Define or discover the project page map
+6. Create or update Pencil designs for the required pages
+7. Bind implementation pages to Pencil pages
+8. Read Pencil design data through MCP
+9. Generate implementation tasks
+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
 
@@ -143,18 +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`
-3. `design-brief.md`
-4. `design-registry.md`
-5. `page-map.md`
-6. `proposal.md`
-7. `specs/<capability>/spec.md`
-8. `design.md`
-9. `pencil-design.md`
-10. `pencil-bindings.md`
-11. `tasks.md`
-12. `verification.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`
 
 Not every mode requires every artifact.
 
@@ -177,6 +217,7 @@ Optional artifacts:
 
 - `brainstorm.md`: raw ideas, tensions, themes, and synthesis notes before specs are stable
 - `project-inventory.md`: discovered routes, pages, modules, and current UI patterns from an existing codebase
+- `DA-VINCI.md`: project-level visual contract for theme, color system, surface treatment, typography direction, and cross-page style rules
 - `design-brief.md`: form factor, visual direction, density, brand constraints, and UI preferences
 - `design-registry.md`: project-level `.pen` file inventory and active design sources
 - `page-map.md`: canonical page list, page responsibilities, route mapping, and page states
@@ -188,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`
 
-`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` -> `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` -> `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 -> `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
 
@@ -227,16 +302,63 @@ 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
 
 Use `design-registry.md` as the project-level inventory of `.pen` sources.
 
+Use `DA-VINCI.md` as the project-level visual source of truth for:
+
+- theme and palette
+- background and surface treatment
+- typography direction
+- component tone
+- rules for cross-page consistency
+
 When a relevant mapping already exists:
 
 - iterate on the mapped Pencil source
 - do not create a new design baseline unless there is a reason
 
+When `DA-VINCI.md` already exists:
+
+- use it as the baseline visual contract
+- do not regenerate visual direction from scratch unless the change explicitly rebrands or resets the product style
+
 When page-to-Pencil bindings already exist:
 
 - update the mapped Pencil page for the affected implementation page
@@ -253,6 +375,7 @@ When neither mappings nor usable design sources exist:
 
 - state that the project is entering baseline reconstruction
 - create a new Pencil baseline from the current local source of truth
+- generate `DA-VINCI.md` from inferred or user-provided design rules before generating many unrelated pages
 
 If the request is too vague to design or implement safely, ask a short clarification question before generating artifacts.