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:

npm install -g @xenonbyte/da-vinci

Install platform assets:

da-vinci install --platform codex,claude,gemini

Useful commands:

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:

$da-vinci <request>

Claude

Preferred:

/da-vinci <request>

Gemini

Preferred:

/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

$da-vinci use greenfield-spec to break down a new desktop software project for annotated design delivery

Brainstorm synthesis

$da-vinci use greenfield-brainstorm to turn several product ideas into a page map, Pencil design plan, and implementation tasks

Redesign from code

$da-vinci use redesign-from-code to inventory the existing app, identify current pages, and generate a new Pencil-backed UI plan

Feature change

$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

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