@xenonbyte/da-vinci-workflow 0.1.3 → 0.1.5

package/README.md

@@ -27,13 +27,14 @@ This workflow is intended for:
 
 Current npm release target:
 
-- `@xenonbyte/da-vinci-workflow@0.1.3`
+- `@xenonbyte/da-vinci-workflow@0.1.5`
 
 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
+- `da-vinci status` now validates full installed asset sets across Codex, Claude, and Gemini
+- Claude and Gemini command adapters now use self-contained workflow wording after installation
+- Node-first install, uninstall, status, and asset validation commands remain the supported distribution path
+- repo-local forward-test example for a `greenfield-spec` workflow remains included
 
 ## Supported workflow modes
 
@@ -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
 
@@ -325,5 +365,5 @@ The repository currently contains:
 
 Next natural work for the repository:
 
-1. add install/distribution helpers
-2. forward-test the workflow on a real project
+1. add automated regression coverage for install, uninstall, and status integrity checks
+2. forward-test the workflow on a real project with a committed `.pen` source

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/commands/claude/da-vinci.md

@@ -3,7 +3,7 @@ description: Da Vinci workflow command index for Claude
 ---
 # Da Vinci
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Platform: Claude
 Default workflow entry: `/da-vinci <request>`
@@ -19,5 +19,4 @@ Notes:
 - Requirements decide behavior.
 - Pencil decides presentation.
 - Code must follow both.
-- Use `references/platform-adapters.md` for shared invocation rules.
-- Use `references/checkpoints.md` when running workflow checkpoints.
+- Keep workflow semantics shared across Codex, Claude, and Gemini.

package/commands/claude/dv/breakdown.md

@@ -3,7 +3,7 @@ description: Break requirements into scope, flows, states, and specs for Da Vinc
 ---
 # Da Vinci Breakdown
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `breakdown`
 

package/commands/claude/dv/build.md

@@ -3,7 +3,7 @@ description: Build software from requirements and Pencil design data for Da Vinc
 ---
 # Da Vinci Build
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `build`
 

package/commands/claude/dv/design.md

@@ -3,7 +3,7 @@ description: Create or refine Pencil-backed design plans for Da Vinci.
 ---
 # Da Vinci Design
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `design`
 

package/commands/claude/dv/tasks.md

@@ -3,7 +3,7 @@ description: Generate implementation tasks from requirements and Pencil designs
 ---
 # Da Vinci Tasks
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `tasks`
 

package/commands/claude/dv/verify.md

@@ -3,7 +3,7 @@ description: Verify requirement coverage, Pencil coverage, and drift for Da Vinc
 ---
 # Da Vinci Verify
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `verify`
 

package/commands/gemini/da-vinci.toml

@@ -5,7 +5,7 @@ description: Da Vinci workflow command index for Gemini
 ---
 # Da Vinci
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Platform: Gemini
 Default workflow entry: `/da-vinci <request>`

package/commands/gemini/dv/breakdown.toml

@@ -2,7 +2,7 @@ description = "Break requirements into scope, flows, states, and specs for Da Vi
 prompt = """
 # Da Vinci Breakdown
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `breakdown`
 

package/commands/gemini/dv/build.toml

@@ -2,7 +2,7 @@ description = "Build software from requirements and Pencil design data for Da Vi
 prompt = """
 # Da Vinci Build
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `build`
 

package/commands/gemini/dv/design.toml

@@ -2,7 +2,7 @@ description = "Create or refine Pencil-backed design plans for Da Vinci."
 prompt = """
 # Da Vinci Design
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `design`
 

package/commands/gemini/dv/tasks.toml

@@ -2,7 +2,7 @@ description = "Generate implementation tasks from requirements and Pencil design
 prompt = """
 # Da Vinci Tasks
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `tasks`
 

package/commands/gemini/dv/verify.toml

@@ -2,7 +2,7 @@ description = "Verify requirement coverage, Pencil coverage, and drift for Da Vi
 prompt = """
 # Da Vinci Verify
 
-Use the `da-vinci` skill for this request.
+Use the Da Vinci workflow for this request.
 
 Action: `verify`