@xenonbyte/da-vinci-workflow 0.1.2

package/references/checkpoints.md

@@ -0,0 +1,141 @@
+# Checkpoints
+
+Use these checkpoint rules for Da Vinci.
+
+## Execution Policy
+
+Treat checkpoints as internal execution guards, not approval steps.
+
+Default handling:
+
+- `PASS`: continue automatically
+- `WARN`: record the issue and continue automatically
+- `BLOCK`: stop only when the blocker cannot be resolved from existing artifacts, local context, or the current codebase
+
+Do not pause the workflow just because a checkpoint ran.
+
+## `discovery checkpoint`
+
+Run after `brainstorm.md`, `project-inventory.md`, or `design-brief.md`.
+
+Check:
+
+- the active mode is correct
+- the starting material is stable enough to write specs
+- product form factor and visual direction are known, inferred, or explicitly deferred
+- candidate pages or current pages are clear enough to move into `page-map.md`
+- open questions are explicitly tracked
+
+Result meanings:
+
+- `PASS`: move into formal proposal/spec work
+- `WARN`: continue, but the foundation is still soft
+- `BLOCK`: do not produce downstream artifacts yet
+
+## `spec checkpoint`
+
+Run after the core requirements and page scope are defined and before Pencil design is treated as final.
+
+Check:
+
+- page scope is complete
+- user flows are named
+- important states are present
+- acceptance conditions are testable
+- risky areas are called out early
+
+Result meanings:
+
+- `PASS`: safe to continue into final design and task planning
+- `WARN`: continue, but update artifacts soon
+- `BLOCK`: update source artifacts before moving on
+
+## `design checkpoint`
+
+Run after Pencil pages exist and before implementation tasks are locked.
+
+Check:
+
+- each required page exists in Pencil
+- important sections exist
+- 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
+
+Result meanings:
+
+- `PASS`: safe to generate implementation tasks
+- `WARN`: minor design gaps exist
+- `BLOCK`: design is not ready to drive implementation
+
+## `mapping checkpoint`
+
+Run after `design-registry.md` and `pencil-bindings.md`.
+
+Check:
+
+- the correct `.pen` source is identified
+- each implementation page has a Pencil page or an explicit exception
+- shared layouts and shared regions are bound clearly enough to implement from
+- route names and Pencil names are traceable
+- missing bindings are called out before implementation
+
+Result meanings:
+
+- `PASS`: safe to generate implementation tasks
+- `WARN`: some bindings are weak, but implementation can continue carefully
+- `BLOCK`: implementation would guess too much without fixing bindings
+
+## `task checkpoint`
+
+Run before implementation starts.
+
+Check:
+
+- top-level task groups exist
+- tasks cover page structure from Pencil
+- tasks cover behavior from specs
+- tasks cover integration and verification work
+- tasks are ordered by dependency
+
+Result meanings:
+
+- `PASS`: safe to start implementation
+- `WARN`: implementation can start, but task quality is weak
+- `BLOCK`: rewrite tasks before implementation
+
+## `execution checkpoint`
+
+Run after each top-level task group during implementation.
+
+Check:
+
+- completed code still matches spec behavior
+- completed code still matches Pencil-backed structure
+- no major scope drift appeared
+- next task group is still valid
+
+Result meanings:
+
+- `PASS`: continue
+- `WARN`: continue, but record the issue
+- `BLOCK`: update artifacts before continuing
+
+## Reporting Format
+
+Use this reporting shape:
+
+```md
+## Checkpoint
+- Type:
+- Status:
+
+## Findings
+- Key point 1
+- Key point 2
+
+## Next Step
+- Continue or update artifacts
+```
+
+Do not create separate review artifacts unless the project explicitly requires them.

package/references/design-inputs.md

@@ -0,0 +1,55 @@
+# Design Inputs
+
+Use this reference when collecting product form factor, UI direction, and design preferences.
+
+## Minimum Inputs
+
+Collect or infer:
+
+1. form factor
+   - desktop software
+   - web app
+   - tablet
+   - mobile app
+
+2. visual direction
+   - minimal
+   - dense workspace
+   - brand-forward
+   - enterprise
+   - editorial
+   - utility-first
+
+3. preference details
+   - dark or light
+   - high or low density
+   - strong or restrained branding
+
+4. constraints
+   - existing design system
+   - existing brand
+   - existing layout shell
+   - responsive priority
+
+## Inference Order
+
+Infer in this order:
+
+1. existing artifacts
+2. existing codebase
+3. user statements
+4. direct clarification
+
+## When To Ask
+
+Ask concise questions only when the answer materially changes Pencil output.
+
+Examples:
+
+- desktop software or web app
+- dark or light base direction
+- dense productivity UI or spacious marketing UI
+
+## Record The Result
+
+Write stable answers into `design-brief.md`.

package/references/modes.md

@@ -0,0 +1,84 @@
+# Workflow Modes
+
+Use these mode definitions when selecting how Da Vinci should start work.
+
+## `greenfield-spec`
+
+Use when:
+
+- the project is new
+- requirements are already clear enough to write specs
+
+Entry artifacts:
+
+- `design-brief.md`
+- `proposal.md`
+- `specs/<capability>/spec.md`
+- `page-map.md`
+
+Best for:
+
+- 0-to-1 product work with a stable brief
+- page sets that can be designed directly after requirement breakdown
+
+## `greenfield-brainstorm`
+
+Use when:
+
+- the project is new
+- requirements are spread across multiple rounds of rough ideas
+
+Entry artifacts:
+
+- `brainstorm.md`
+- `design-brief.md`
+- then `proposal.md`
+- then `specs/<capability>/spec.md`
+- then `page-map.md`
+
+Best for:
+
+- founder ideation
+- product discovery sessions
+- messy early-stage requests that need synthesis before design
+
+## `redesign-from-code`
+
+Use when:
+
+- an existing project already has routes, pages, and UI
+- the goal is a broad UI replacement or redesign
+
+Entry artifacts:
+
+- `project-inventory.md`
+- `design-registry.md`
+- `proposal.md`
+- `specs/<capability>/spec.md`
+- `page-map.md`
+
+Best for:
+
+- full visual refresh
+- layout modernization
+- design-system replacement
+
+## `feature-change`
+
+Use when:
+
+- the project already exists
+- the change affects only part of the system
+
+Entry artifacts:
+
+- `proposal.md`
+- `specs/<capability>/spec.md`
+- affected `design-registry.md`
+- affected subset of `page-map.md`
+
+Best for:
+
+- new feature pages
+- changing existing pages
+- scoped UX or workflow changes

package/references/page-mapping.md

@@ -0,0 +1,47 @@
+# Page Mapping
+
+Use this reference when the workflow must connect requirements, Pencil pages, and implementation pages.
+
+## Canonical Rule
+
+Treat `page-map.md` as the source of truth for implementation pages.
+
+Treat `design-registry.md` as the source of truth for available `.pen` sources.
+
+Treat `pencil-bindings.md` as the source of truth for:
+
+- implementation page -> Pencil page
+- route -> Pencil screen
+- shared region -> Pencil region
+
+## Mapping Rules
+
+- define one canonical implementation page name per page
+- define one canonical Pencil page or screen per implementation page when possible
+- if multiple implementation pages share one Pencil page, record the reason
+- if one implementation page needs multiple Pencil screens, record the sub-page or state split
+
+## Minimum Binding Shape
+
+Use a simple mapping line:
+
+```md
+- `/settings/billing` -> `Billing Settings Screen`
+```
+
+For shared regions:
+
+```md
+- `App sidebar` -> `Navigation Shell`
+```
+
+## When To Block
+
+Treat bindings as insufficient when:
+
+- no active `.pen` source is registered
+- the implementation page has no Pencil source
+- the Pencil page exists but cannot be traced to a route or page responsibility
+- shared layout regions are undefined and implementation would guess too much
+
+In those cases, stop at the `mapping checkpoint` and update the artifacts.

package/references/pencil-design-to-code.md

@@ -0,0 +1,64 @@
+# Pencil Design To Code
+
+Use this reference when implementation must follow Pencil data.
+
+## Source Priority
+
+Use this priority order:
+
+1. requirement artifacts for behavior
+2. Pencil data for presentation
+3. screenshots only as a visual check
+
+Do not infer behavior from appearance alone.
+
+## Read From Pencil
+
+When MCP is available, read:
+
+- active `.pen` file
+- target page frame
+- child section hierarchy
+- text content
+- layout direction
+- gap and padding
+- width and height strategy
+- fills, strokes, corners, and major visual grouping
+
+Prefer structural reads over screenshots.
+
+## Map Pencil To Frontend
+
+Use these default mappings:
+
+- vertical frame -> column flex container
+- horizontal frame -> row flex container
+- gap -> `gap-*` or arbitrary gap utilities
+- padding -> `p-*` or directional padding utilities
+- fill -> background utilities or custom CSS values
+- text nodes -> semantic headings, paragraphs, labels, buttons
+
+When the project uses Tailwind:
+
+- preserve layout and spacing first
+- preserve typography second
+- preserve decorative effects third
+
+## Implementation Discipline
+
+When coding from Pencil:
+
+- keep section order aligned with Pencil
+- keep content hierarchy aligned with Pencil
+- keep major CTA placement aligned with Pencil
+- extract reusable blocks only when the grouping is stable
+- do not flatten the layout so aggressively that the design structure disappears
+
+## Verification
+
+Before treating the code as complete:
+
+- compare major sections against Pencil
+- compare headline and CTA hierarchy against Pencil
+- compare panel grouping against Pencil
+- note any intentional deviations

package/references/platform-adapters.md

@@ -0,0 +1,66 @@
+# Platform Adapters
+
+Use these invocation patterns when guiding users across platforms.
+
+## Codex
+
+Preferred:
+
+```text
+$da-vinci <request>
+```
+
+Mode examples:
+
+```text
+$da-vinci use greenfield-spec to break down a new SaaS project
+$da-vinci use greenfield-brainstorm to synthesize product ideas into pages and specs
+$da-vinci use redesign-from-code to inventory the current app and redesign the UI
+$da-vinci use feature-change to add a new billing page and generate Pencil-backed tasks
+```
+
+Use this for:
+
+- requirement breakdown
+- Pencil page generation planning
+- design-to-code implementation
+
+If explicit routes are added later, treat them as routing helpers, not the only entrypoint.
+
+## Claude
+
+Preferred:
+
+```text
+/da-vinci <request>
+```
+
+Use the same workflow stages as Codex:
+
+- requirement
+- design
+- tasks
+- implementation
+- verification
+
+## Gemini
+
+Preferred:
+
+```text
+/da-vinci <request>
+```
+
+Keep the same artifact names and checkpoint names across platforms.
+
+## Cross-Platform Rule
+
+Keep these stable:
+
+- artifact names
+- checkpoint names
+- drift policy
+- requirement/design/code contract
+- mode names
+
+Platform adapters may differ in command syntax, but not in workflow semantics.

package/scripts/postinstall.js

@@ -0,0 +1,9 @@
+const { VERSION } = require("../lib/install");
+
+console.log(
+  [
+    `Da Vinci v${VERSION} installed.`,
+    "Next step:",
+    "  da-vinci install --platform codex,claude,gemini"
+  ].join("\n")
+);

package/scripts/validate-assets.js

@@ -0,0 +1,9 @@
+const { validateAssets, VERSION } = require("../lib/install");
+
+try {
+  const result = validateAssets();
+  console.log(`Da Vinci v${VERSION} assets are complete (${result.requiredAssets} required files).`);
+} catch (error) {
+  console.error(error.message || String(error));
+  process.exit(1);
+}