---
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.