@xenonbyte/da-vinci-workflow 0.1.2 → 0.1.4

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/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.4",
   "description": "Requirement-to-design-to-code workflow skill for Codex, Claude, and Gemini",
   "bin": {
     "da-vinci": "bin/da-vinci.js"