@xenonbyte/da-vinci-workflow 0.1.2 → 0.1.4

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,72 @@ 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:
+
+```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.
+
+Recommended path:
+
+- `DA-VINCI.md`
+
 ## `design-brief.md`
 
 Use this structure:
@@ -98,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:
@@ -124,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:
@@ -156,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:
@@ -191,6 +304,10 @@ Use this structure:
 - Observable outcomes
 ```
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/proposal.md`
+
 ## `specs/<capability>/spec.md`
 
 Use this structure:
@@ -229,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:
@@ -260,6 +381,10 @@ Use this structure:
 - Unresolved design decisions
 ```
 
+Recommended path:
+
+- `.da-vinci/changes/<change-id>/design.md`
+
 ## `pencil-design.md`
 
 Use this structure:
@@ -290,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:
@@ -316,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:
@@ -339,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:
@@ -362,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,25 @@ 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:
+
+- 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`.
@@ -43,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:
 
@@ -50,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.
@@ -61,6 +88,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:
 
@@ -97,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.
@@ -121,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/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.

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: