@xenonbyte/da-vinci-workflow 0.1.2 → 0.1.3

package/README.md

@@ -23,6 +23,18 @@ 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.3`
+
+Release highlights:
+
+- project-level visual contract support through `DA-VINCI.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,14 +61,15 @@ 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
 
@@ -64,6 +77,7 @@ Depending on the mode, the workflow may use these artifacts:
 
 - `brainstorm.md`
 - `project-inventory.md`
+- `DA-VINCI.md`
 - `design-brief.md`
 - `design-registry.md`
 - `page-map.md`
@@ -79,6 +93,7 @@ Depending on the mode, the workflow may use these artifacts:
 
 - `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
@@ -137,6 +152,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 +174,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 +183,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
 

package/SKILL.md

@@ -30,6 +30,7 @@ That means:
 Continue automatically through:
 
 - mode selection
+- project visual-contract detection
 - requirement breakdown
 - page mapping
 - design input collection
@@ -85,6 +86,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 +111,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 +125,15 @@ 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
 
 ## Load References On Demand
 
@@ -145,16 +153,17 @@ 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`
+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`
 
 Not every mode requires every artifact.
 
@@ -177,6 +186,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
@@ -194,19 +204,19 @@ Use these minimum flows:
 
 ### `greenfield-spec`
 
-`design-brief` -> `proposal` -> `specs` -> `page-map` -> `design-registry` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
+`DA-VINCI` -> `design-brief` -> `proposal` -> `specs` -> `page-map` -> `design-registry` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
 
 ### `greenfield-brainstorm`
 
-`brainstorm` -> `design-brief` -> `proposal` -> `specs` -> `page-map` -> `design-registry` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
+`brainstorm` -> `DA-VINCI` -> `design-brief` -> `proposal` -> `specs` -> `page-map` -> `design-registry` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
 
 ### `redesign-from-code`
 
-`project-inventory` -> `design-registry` -> `proposal` -> `specs` -> `page-map` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
+`project-inventory` -> `DA-VINCI` -> `design-registry` -> `proposal` -> `specs` -> `page-map` -> `design` -> `pencil-design` -> `pencil-bindings` -> `tasks` -> `verification`
 
 ### `feature-change`
 
-`proposal` -> `specs` -> `page-map` for affected pages -> `design-registry` -> `design` -> `pencil-design` delta -> `pencil-bindings` delta -> `tasks` -> `verification`
+`proposal` -> `specs` -> `page-map` for affected pages -> `DA-VINCI` -> `design-registry` -> `design` -> `pencil-design` delta -> `pencil-bindings` delta -> `tasks` -> `verification`
 
 ## Requirement Breakdown Rules
 
@@ -232,11 +242,24 @@ If the active mode is `redesign-from-code`:
 
 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 +276,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.
 

package/examples/greenfield-spec-markupflow/DA-VINCI.md

@@ -0,0 +1,49 @@
+# DA-VINCI
+
+## Product Surface
+- desktop software
+- desktop-first launch pages
+
+## Visual Direction
+- dark tool-like product marketing
+- technical but polished
+- high-contrast hierarchy
+
+## Theme
+- primary color: `#A855F7`
+- accent color: `#EC4899`
+- background color: `#06070A`
+- panel color: `#10131A`
+- border color: `#2A3142`
+- primary text color: `#FFFFFF`
+- secondary text color: `#A1A1AA`
+
+## Typography
+- display direction: bold geometric sans
+- body direction: neutral sans for dense product copy
+- mono usage: metadata, labels, and process cues
+
+## Layout Rules
+- desktop-first
+- wide hero sections
+- dark panels with occasional light contrast surfaces
+- rounded panels and strong internal spacing
+
+## Component Tone
+- buttons should feel direct and product-oriented
+- content panels should look like software surfaces, not generic blog cards
+- CTA regions should preserve the same dark product language
+
+## Do
+- keep page sections clearly bounded
+- use contrast panels to explain structured output
+- keep technical cues visible in labels and metadata
+
+## Do Not
+- switch to unrelated bright themes on later pages
+- replace the desktop-product tone with consumer lifestyle styling
+- generate unrelated type or spacing systems for each page
+
+## Source Of Truth
+- inferred from the MarkupFlow forward-test product description
+- aligned with the active Pencil screens `MarkupFlow Homepage` and `MarkupFlow Product Detail`

package/examples/greenfield-spec-markupflow/README.md

@@ -10,11 +10,13 @@ Scenario:
 
 - a desktop-software product named `MarkupFlow`
 - two launch pages
+- one project-level visual contract
 - Pencil-backed design source
 - static `HTML + Tailwind` implementation
 
 Files in this example:
 
+- `DA-VINCI.md`
 - `design-brief.md`
 - `proposal.md`
 - `specs/marketing-site/spec.md`

package/examples/greenfield-spec-markupflow/tasks.md

@@ -1,6 +1,7 @@
 # Tasks
 
 ## 1. Scope And Page Definition
+- [x] define the project visual contract in `DA-VINCI.md`
 - [x] capture the desktop-product design brief
 - [x] define the proposal and delivery scope
 - [x] write the marketing-site behavior spec
@@ -12,6 +13,7 @@
 - [x] register the active Pencil source
 - [x] record the active Pencil screens and implementation notes
 - [x] bind implementation pages to Pencil screens
+- [x] confirm the Pencil screens follow the same `DA-VINCI.md` visual baseline
 - [x] `PASS` design checkpoint
 - [x] `PASS` mapping checkpoint
 

package/examples/greenfield-spec-markupflow/verification.md

@@ -19,6 +19,7 @@
 - product detail page explains desktop workspace modules
 
 ## Design Coverage
+- the implementation follows the project visual contract in `DA-VINCI.md`
 - the homepage implementation follows the Pencil screen structure for hero, capabilities, MCP service, and CTA
 - the product detail implementation follows the Pencil screen structure for workspace hero, pipeline, modules, and CTA
 - implementation pages are explicitly bound to Pencil screen ids

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/da-vinci-workflow",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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

@@ -63,6 +63,64 @@ Use this structure:
 
 Use this artifact when redesign starts from an existing codebase.
 
+## `DA-VINCI.md`
+
+Use this structure:
+
+```md
+# DA-VINCI
+
+## Product Surface
+- desktop software
+- web app
+- tablet
+- mobile app
+
+## Visual Direction
+- product tone
+- density
+- visual intent
+
+## Theme
+- primary color
+- accent color
+- background color
+- panel color
+- border color
+- text hierarchy colors
+
+## Typography
+- display direction
+- body direction
+- mono usage
+
+## Layout Rules
+- desktop-first or mobile-first
+- workspace density
+- spacing tendency
+- corner radius and shadow tendency
+
+## Component Tone
+- button tone
+- panel tone
+- CTA tone
+- navigation tone
+
+## Do
+- approved stylistic moves
+
+## Do Not
+- disallowed stylistic moves
+
+## Source Of Truth
+- user preference
+- existing codebase
+- existing Pencil source
+- inferred baseline
+```
+
+Use this artifact as a project-level visual contract. Generate it when the project does not already have one.
+
 ## `design-brief.md`
 
 Use this structure:

package/references/checkpoints.md

@@ -14,6 +14,20 @@ Default handling:
 
 Do not pause the workflow just because a checkpoint ran.
 
+## Visual Contract Rule
+
+Before broad Pencil page generation:
+
+- detect whether `DA-VINCI.md` exists
+- if it exists, treat it as the visual baseline
+- if it does not exist, generate it from stable inputs before creating many unrelated pages
+
+Use the design checkpoint to confirm:
+
+- `DA-VINCI.md` exists or has been intentionally generated for the current project
+- the current Pencil pages follow the same visual baseline
+- later pages are not re-inventing the product style from scratch
+
 ## `discovery checkpoint`
 
 Run after `brainstorm.md`, `project-inventory.md`, or `design-brief.md`.
@@ -61,6 +75,7 @@ Check:
 - key states are represented or explicitly deferred
 - major layout strategy matches the design artifact
 - Pencil names and artifact names are aligned enough to implement from
+- Pencil pages follow the current `DA-VINCI.md` visual contract
 
 Result meanings:
 

package/references/design-inputs.md

@@ -2,6 +2,14 @@
 
 Use this reference when collecting product form factor, UI direction, and design preferences.
 
+## Visual Contract Detection
+
+Check for `DA-VINCI.md` first.
+
+- if it exists, treat it as the project visual contract
+- if it does not exist, generate it from the best stable inputs before broad Pencil page generation
+- avoid re-deriving the visual language page by page
+
 ## Minimum Inputs
 
 Collect or infer:
@@ -35,10 +43,11 @@ Collect or infer:
 
 Infer in this order:
 
-1. existing artifacts
-2. existing codebase
-3. user statements
-4. direct clarification
+1. `DA-VINCI.md`
+2. existing artifacts
+3. existing codebase
+4. user statements
+5. direct clarification
 
 ## When To Ask
 
@@ -53,3 +62,5 @@ Examples:
 ## Record The Result
 
 Write stable answers into `design-brief.md`.
+
+If `DA-VINCI.md` did not already exist, generate it from those stable answers and save it as the project visual baseline.