# 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
```

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