@xenonbyte/da-vinci-workflow 0.1.2

package/README.md

@@ -0,0 +1,306 @@
+# Da Vinci
+
+Da Vinci is a software delivery workflow that turns product requirements into structured specs, Pencil designs, page-to-design bindings, implementation tasks, and final code.
+
+The workflow is built around one fixed contract:
+
+- requirements decide behavior
+- Pencil decides presentation
+- code follows both
+
+## What Da Vinci is for
+
+Use Da Vinci when software delivery needs all three layers to stay aligned:
+
+1. requirement breakdown
+2. Pencil-backed UI design
+3. implementation from requirements plus design data
+
+This workflow is intended for:
+
+- 0-to-1 product delivery
+- brainstorm-to-product delivery
+- redesign from existing code
+- scoped feature delivery on an existing product
+
+## Supported workflow modes
+
+Da Vinci V2 supports four modes.
+
+### `greenfield-spec`
+
+Use when the project is new and the requirements are already clear enough to write specs.
+
+### `greenfield-brainstorm`
+
+Use when the project is new but the inputs come from multiple rounds of rough product ideation and need synthesis first.
+
+### `redesign-from-code`
+
+Use when an existing project already has routes, pages, and UI, and the goal is a broad redesign or UI replacement.
+
+### `feature-change`
+
+Use when an existing product needs a scoped requirement change, page addition, or page update.
+
+## Core workflow
+
+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
+
+## Default artifacts
+
+Depending on the mode, the workflow may use these artifacts:
+
+- `brainstorm.md`
+- `project-inventory.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`
+
+### Artifact intent
+
+- `brainstorm.md`: raw ideas before specs are stable
+- `project-inventory.md`: current routes, pages, and UI patterns from an existing codebase
+- `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
+- `proposal.md`: change scope and outcomes
+- `spec.md`: behavior, states, edge cases, and acceptance rules
+- `design.md`: page structure, interactions, and component strategy
+- `pencil-design.md`: `.pen` file path, screens, screenshots, and implementation notes
+- `pencil-bindings.md`: implementation page -> Pencil page bindings
+- `tasks.md`: implementation order and task groups
+- `verification.md`: requirement coverage, design coverage, and drift findings
+
+## Checkpoints
+
+Da Vinci uses these checkpoints:
+
+1. `discovery checkpoint`
+2. `spec checkpoint`
+3. `design checkpoint`
+4. `mapping checkpoint`
+5. `task checkpoint`
+6. `execution checkpoint`
+
+Checkpoint outcomes:
+
+- `PASS`
+- `WARN`
+- `BLOCK`
+
+## Execution Policy
+
+Da Vinci is `autonomous-by-default`.
+
+That means:
+
+- it should continue the workflow without pausing for user confirmation at each stage
+- checkpoints are internal quality gates, not approval gates
+- it should only stop when a real blocker exists
+
+Default behavior:
+
+- `PASS` -> continue
+- `WARN` -> record and continue
+- `BLOCK` -> stop only when the blocker cannot be resolved from existing artifacts or local context
+
+Typical stop conditions:
+
+- the user explicitly interrupts
+- a missing input would materially change the design or implementation result
+- an external permission or authentication step is required
+- source artifacts conflict badly enough that continuing would guess the truth
+- a destructive baseline-changing action is about to happen
+
+## Design source policy
+
+Da Vinci treats Pencil as a structured design source, not as a screenshot source.
+
+Rules:
+
+- `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
+
+When a relevant mapping already exists:
+
+- iterate on the mapped Pencil source
+
+When mappings do not exist but local code exists:
+
+- reconstruct the baseline from the local project
+- rebuild inventory, page map, and design registry
+
+When neither mappings nor usable design sources exist:
+
+- create a new Pencil baseline from the current local source of truth
+
+## Design input collection
+
+Before generating Pencil designs for a greenfield project, Da Vinci should collect or infer:
+
+- product form factor
+- visual tone
+- density
+- brand direction
+- responsive priority
+
+Preferred inference order:
+
+1. existing artifacts
+2. project-local signals
+3. explicit user answers
+4. short clarification questions
+
+## Installation
+
+Install the package:
+
+```bash
+npm install -g @xenonbyte/da-vinci-workflow
+```
+
+Install platform assets:
+
+```bash
+da-vinci install --platform codex,claude,gemini
+```
+
+Useful commands:
+
+```bash
+da-vinci status
+da-vinci validate-assets
+da-vinci uninstall --platform codex,claude,gemini
+```
+
+Installation targets:
+
+- Codex prompts: `~/.codex/prompts/`
+- Codex skill: `~/.codex/skills/da-vinci/`
+- Claude commands: `~/.claude/commands/`
+- Gemini commands: `~/.gemini/commands/`
+
+## Platform usage
+
+### Codex
+
+Preferred:
+
+```text
+$da-vinci <request>
+```
+
+### Claude
+
+Preferred:
+
+```text
+/da-vinci <request>
+```
+
+### Gemini
+
+Preferred:
+
+```text
+/da-vinci <request>
+```
+
+## Repo-local forward test
+
+A complete repo-local forward test is available at:
+
+- `examples/greenfield-spec-markupflow/`
+
+That example runs a `greenfield-spec` scenario from:
+
+1. design brief
+2. proposal and spec
+3. page map
+4. Pencil source registration
+5. Pencil page bindings
+6. implementation tasks
+7. static HTML delivery
+8. verification
+
+## Example requests
+
+### Greenfield spec
+
+```text
+$da-vinci use greenfield-spec to break down a new desktop software project for annotated design delivery
+```
+
+### Brainstorm synthesis
+
+```text
+$da-vinci use greenfield-brainstorm to turn several product ideas into a page map, Pencil design plan, and implementation tasks
+```
+
+### Redesign from code
+
+```text
+$da-vinci use redesign-from-code to inventory the existing app, identify current pages, and generate a new Pencil-backed UI plan
+```
+
+### Feature change
+
+```text
+$da-vinci use feature-change to add a billing page, generate the relevant Pencil design delta, and create implementation tasks
+```
+
+## Workflow examples
+
+See:
+
+- `docs/workflow-examples.md`
+
+## Repository layout
+
+```text
+da-vinci/
+├── SKILL.md
+├── agents/
+│   └── openai.yaml
+├── commands/
+│   ├── claude/
+│   ├── codex/
+│   └── gemini/
+├── references/
+└── openspec/
+```
+
+## Current status
+
+The repository currently contains:
+
+- the Da Vinci skill
+- three-platform command adapters
+- workflow references
+- OpenSpec planning artifacts for the skill itself
+- workflow examples
+
+Next natural work for the repository:
+
+1. add install/distribution helpers
+2. forward-test the workflow on a real project

package/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: da-vinci
+description: Drive a software delivery workflow from requirement breakdown to Pencil design generation and finally code implementation. Use when turning product or page requirements into structured specs, page maps, Pencil `.pen` designs, design-backed implementation tasks, and frontend code that must follow both the requirements and the Pencil design data.
+---
+
+# Da Vinci Workflow
+
+Use Da Vinci as a requirement-to-design-to-code workflow for software delivery.
+
+## Core Contract
+
+Keep these rules fixed:
+
+- Requirements decide behavior.
+- Pencil decides presentation.
+- Tasks decide implementation order.
+- Code must follow both requirements and Pencil data.
+- When requirements and Pencil drift apart, stop and update the source artifacts before continuing implementation.
+
+## Execution Policy
+
+Treat Da Vinci as `autonomous-by-default`.
+
+That means:
+
+- continue the workflow without pausing for approval at every stage
+- treat checkpoints as internal execution guards, not approval steps
+- stop only when a true blocking condition exists
+
+Continue automatically through:
+
+- mode selection
+- requirement breakdown
+- page mapping
+- design input collection
+- design source registration
+- Pencil design work
+- page-to-Pencil binding
+- task generation
+- implementation
+- verification
+
+Stop and ask only when:
+
+- the user explicitly interrupts
+- a missing input would materially change the result
+- an external permission, authentication step, or protected environment is required
+- source artifacts conflict badly enough that continuing would guess the truth
+- a destructive action would change the project baseline significantly
+
+## Invocation Model
+
+Canonical workflow name is `da-vinci`.
+
+- Codex preferred: `$da-vinci <request>`
+- Claude and Gemini preferred: `/da-vinci <request>` when platform adapters exist
+- Explicit action routes may exist later, but natural-language invocation is the default path
+
+## V2 Mode Selection
+
+Select one workflow mode before producing artifacts.
+
+Supported modes:
+
+1. `greenfield-spec`
+   - use when the project starts from a clear product or page requirement
+
+2. `greenfield-brainstorm`
+   - use when the project starts from multiple rounds of raw ideas and needs synthesis first
+
+3. `redesign-from-code`
+   - use when an existing product already has code and the UI must be redesigned globally or broadly
+
+4. `feature-change`
+   - use when an existing product needs a scoped requirement change, page addition, or page update
+
+If the user does not specify a mode:
+
+- choose `greenfield-spec` for new projects with clear requirements
+- choose `greenfield-brainstorm` for exploratory new product ideation
+- choose `redesign-from-code` for broad UI replacement on existing code
+- choose `feature-change` for incremental product work
+
+## Design Input Collection
+
+Before generating new Pencil designs for a greenfield project, collect or infer:
+
+1. product form factor
+   - desktop software
+   - web app
+   - tablet
+   - mobile app
+
+2. design preference
+   - visual tone
+   - density
+   - brand direction
+   - light or dark preference
+
+3. design constraints
+   - existing brand rules
+   - existing design system
+   - responsive priority
+   - delivery constraints
+
+Use this priority order:
+
+1. existing workflow artifacts
+2. project-local config or project codebase signals
+3. explicit user answers
+4. short clarification questions
+
+Do not repeatedly ask for inputs that are already stable in the artifacts.
+
+## Default Workflow
+
+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
+
+## Load References On Demand
+
+Load only the reference that matches the current step:
+
+- Read `references/modes.md` when selecting or explaining a workflow mode
+- Read `references/artifact-templates.md` when creating or updating workflow artifacts
+- Read `references/checkpoints.md` when running or reporting checkpoints
+- Read `references/design-inputs.md` when collecting product form factor, style, and constraints
+- Read `references/page-mapping.md` when defining project pages, Pencil pages, and route-to-screen bindings
+- Read `references/pencil-design-to-code.md` when turning Pencil data into implementation
+- Read `references/platform-adapters.md` when guiding users on Codex, Claude, or Gemini invocation patterns
+
+## Default Artifacts
+
+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`
+
+Not every mode requires every artifact.
+
+Mode expectations:
+
+1. `proposal.md`
+2. `specs/<capability>/spec.md`
+3. `design.md`
+4. `pencil-design.md`
+5. `tasks.md`
+6. `verification.md`
+
+Optional artifacts:
+
+- `security-review.md`
+- `migration-plan.md`
+- `rollout-checklist.md`
+
+## What Each Artifact Means
+
+- `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
+- `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
+- `proposal.md`: scope, goal, non-goals, and success criteria
+- `spec.md`: behavior, states, inputs, outputs, edge cases, and acceptance rules
+- `design.md`: information architecture, page structure, interaction model, and component strategy
+- `pencil-design.md`: `.pen` file path, page mapping, selected screens, screenshots, and design notes
+- `pencil-bindings.md`: implementation route or component -> Pencil page or screen binding
+- `tasks.md`: implementation order and deliverable task groups
+- `verification.md`: requirement coverage, Pencil coverage, and drift findings
+
+## Mode-Specific Artifact Flow
+
+Use these minimum flows:
+
+### `greenfield-spec`
+
+`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`
+
+### `redesign-from-code`
+
+`project-inventory` -> `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`
+
+## Requirement Breakdown Rules
+
+Before designing or coding:
+
+- Split the request into pages, flows, states, and data dependencies
+- Identify which parts are visual, behavioral, and integration-related
+- Separate must-have scope from later improvements
+- Call out risky areas early: auth, permissions, uploads, payments, admin flows, secrets, migrations
+
+If the active mode is `greenfield-brainstorm`:
+
+- synthesize repeated ideas into stable product direction first
+- identify contradictions before writing specs
+- move unresolved ideas into open questions instead of treating them as requirements
+
+If the active mode is `redesign-from-code`:
+
+- inventory current routes, pages, and modules before redefining page structure
+- distinguish preserved behavior from replaced presentation
+
+## Design Source Rules
+
+Use `design-registry.md` as the project-level inventory of `.pen` sources.
+
+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 page-to-Pencil bindings already exist:
+
+- update the mapped Pencil page for the affected implementation page
+
+When project mappings do not exist but existing code exists:
+
+- treat the current project as the baseline source
+- reconstruct `project-inventory.md`
+- reconstruct `page-map.md`
+- create or rebuild `design-registry.md`
+- generate a new Pencil baseline only after the inventory is stable
+
+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
+
+If the request is too vague to design or implement safely, ask a short clarification question before generating artifacts.
+
+## Pencil Design Rules
+
+Use Pencil as a structured UI source, not as a static image source.
+
+When creating or editing Pencil designs:
+
+- Build the pages required by the current scope, not an abstract moodboard
+- follow `page-map.md` as the canonical page list
+- follow `design-brief.md` for form factor and visual direction when it exists
+- Keep page names, section names, and labels aligned with the specs
+- Make important states explicit when they change implementation: empty, loading, success, error, restricted, unavailable
+- Prefer layout clarity and information hierarchy over decorative complexity
+- After changes, inspect the result visually before treating it as implementation-ready
+
+When multiple pages exist:
+
+- keep one canonical Pencil page or screen per implementation page
+- record the `.pen` file in `design-registry.md`
+- record the mapping in `pencil-bindings.md`
+
+## Pencil MCP Rules
+
+When Pencil is available through MCP:
+
+- Read the active `.pen` file and page structure before coding
+- read the bound Pencil page for the current implementation page
+- Use Pencil data to extract layout, text, hierarchy, panels, buttons, and content regions
+- Use screenshots only as a secondary visual check
+- Treat Pencil as the design data source for presentation, spacing, and layout grouping
+
+When Pencil is not available:
+
+- State that the design-backed path is unavailable
+- Fall back to requirements-first implementation and note the missing design constraint
+
+## Implementation Rules
+
+When generating code:
+
+- Use requirements to determine behavior, states, conditions, and semantics
+- Use Pencil to determine layout, section ordering, visual grouping, copy placement, and styling intent
+- use `pencil-bindings.md` to decide which Pencil page or screen maps to the page being implemented
+- Do not invent interaction behavior from design alone
+- Do not ignore Pencil structure when writing markup
+- Keep code organized by page sections and reusable UI blocks when that mapping is clear
+
+For frontend work:
+
+- Prefer `HTML + Tailwind`, `React + Tailwind`, or the project's existing frontend stack
+- Preserve the dominant page structure from Pencil
+- Match spacing and hierarchy before polishing effects
+
+## Checkpoints
+
+Run these checkpoints:
+
+1. `discovery checkpoint`
+   - after `brainstorm.md`, `project-inventory.md`, or `design-brief.md`
+   - verify the mode-specific starting material is stable enough to move into specs and design work
+
+2. `spec checkpoint`
+   - after requirements and page scope are defined
+   - verify page scope, states, and behavior coverage
+
+3. `design checkpoint`
+   - after Pencil design exists, before implementation tasks are locked
+   - verify the design covers the required pages, states, and key interactions
+
+4. `mapping checkpoint`
+   - after `design-registry.md` and `pencil-bindings.md`
+   - verify implementation pages and Pencil pages are bound correctly
+
+5. `task checkpoint`
+   - before implementation starts
+   - verify tasks cover both requirements and Pencil-backed UI work
+
+6. `execution checkpoint`
+   - after each top-level task group during implementation
+   - verify code still matches requirements and Pencil structure
+
+Checkpoint states:
+
+- `PASS`
+- `WARN`
+- `BLOCK`
+
+Checkpoint handling:
+
+- `PASS`: continue automatically
+- `WARN`: record the issue and continue automatically
+- `BLOCK`: stop, report the blocker, and ask only if the blocker cannot be resolved from existing artifacts
+
+## Drift Policy
+
+Treat these as drift:
+
+- Requirement changed but Pencil was not updated
+- Page map changed but Pencil bindings were not updated
+- Design registry changed but downstream bindings were not updated
+- Pencil changed but implementation tasks were not updated
+- Code behavior exceeds the approved scope
+- Code layout or content structure diverges materially from Pencil without a recorded reason
+
+When drift is found:
+
+- Update the source artifact first
+- Then continue implementation
+
+## Output Format
+
+After meaningful work, report:
+
+1. changed files
+2. active mode
+3. current workflow state
+4. next recommended step
+5. blockers or drift
+
+Keep updates concise and operational.

package/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Da Vinci"
+  short_description: "Requirement-to-design-to-code software workflow"
+  default_prompt: "Use $da-vinci to choose the right delivery mode and turn a software requirement into Pencil designs and implementation tasks."
+
+policy:
+  allow_implicit_invocation: false

package/bin/da-vinci.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../lib/cli");
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(error.message || String(error));
+  process.exit(1);
+});