name	da-vinci
description	Drive a software delivery workflow from supplement requirements through da-vinci-pencli-backed UI design, task planning, implementation, and verification. Use when product or page work must stay aligned across requirement truth, design truth, and implementation evidence.

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.
Da Vinci PenCLI decides presentation.
Tasks decide implementation order.
Code must follow both requirements and .dvp design data.
Each new requirement iteration stays in its own change directory.
Workflow markdown for a target project belongs under .da-vinci/changes/<change-id>/; do not create target-project root-level proposal.md, specs/, design.md, tasks.md, or verification.md while running the Da Vinci workflow.
Prior changes are inherited evidence, not automatic current truth.
When requirements and registered .dvp design truth drift apart, stop and update the source artifacts before continuing implementation.

Execution Policy

Treat Da Vinci as phase-driven, not autonomous-through-every-handoff.

That means:

continue working inside the current phase until its truth is stable
do not auto-promote between phases just because checkpoints are green
require explicit handoff review before promotion
use dv-handoff when the current phase is ready for review
keep full-delivery as the default intent only within the currently legal route chain

Stop and ask only when:

the user explicitly interrupts
a missing input would materially change the result
an external permission/authentication/protected environment step is required
source artifacts conflict badly enough that continuing would guess the truth
a destructive action would change the project baseline significantly
the current phase is waiting for explicit handoff review

Route Discipline

When Da Vinci reports a “next recommended step”, keep it stateful and singular:

start new work with dv-breakdown
treat dv-breakdown as the user-facing supplement requirements phase
use dv-continue only to resume or recover current route truth
use dv-handoff only for explicit cross-phase review
if pendingHandoff is present because review is still missing or WARN needs explicit acceptance, recommend dv-handoff
if pendingHandoff is rejected, stale, or blocked by owner-stage truth, route back to the owner stage instead of repeating dv-handoff
if UI design reveals a requirement gap, route back to dv-breakdown
if design work only adds mapped states or variants, stay in dv-design
if design is ready but tasks.md does not exist, recommend dv-tasks
if tasks.md exists and task handoff is accepted, recommend dv-build
if implementation evidence exists and verification is the remaining legal step, recommend dv-verify

Hard rules:

do not present build as a co-equal next step when tasks.md does not exist
do not present build immediately after design completion when task generation is still missing
do not add a top-level handoff stage to the workflow stage ids
if multiple commands are shown, clearly mark one primary route
when dv-handoff records an accepted outcome, write .da-vinci/changes/<change-id>/handoffs/<gate>.json before appending the final parseable marker
keep the accepted marker append as the last substantive edit to the owning artifact
fail closed when an accepted marker is missing durable evidence envelope .da-vinci/changes/<change-id>/handoffs/<gate>.json or that envelope is invalid
keep exact stage payload schemas out of this core file; read references/skill-workflow-detail.md on demand when a handoff needs stage-specific detail

Invocation Model

Canonical workflow name is da-vinci.

Codex canonical direct routes: $dv-breakdown for new work, $dv-continue to resume, $dv-handoff for review, plus $dv-design, $dv-tasks, $dv-build, $dv-verify, $dv-change-new, $dv-change-close, $dv-change-recover, $dv-code-context, and $dv-repair
Claude/Gemini direct routes: /dv-breakdown, /dv-continue, /dv-handoff, /dv-design, /dv-tasks, /dv-build, /dv-verify, /dv-change-new, /dv-change-close, /dv-change-recover, /dv-code-context, and /dv-repair
User-facing command set: breakdown, continue, handoff, design, tasks, build, verify
Project-level advisory helper: code-context

New-work and resume rules:

new work starts at breakdown
resumed work starts at continue
phase review always uses handoff
project-level code inventory refresh may use code-context without an active change; it does not alter route truth
workflow-status and next-step are the route-truth surfaces before free-form continuation

Design Review Gate

Core contract reminders:

reviewer configuration and da-vinci supervisor-review evidence must remain explicit in workflow artifacts.
when supervisor review is required, missing/blocked/unaccepted review is a blocker before terminal completion.

Core File Boundary

Treat this file as the runtime map, not the full manual.

Keep invariant route and execution truth here.
Move stage-specific procedure to references/skill-workflow-detail.md.
Move operator and maintainer explanation to README.md and docs/.
If this file starts repeating a long doc section, replace the duplicate with an on-demand reference.

Load References On Demand

Load only the reference that matches the active stage:

Read references/artifact-templates.md when creating/updating workflow artifacts.
Read references/checkpoints.md when running/reporting checkpoints.
Read references/design-inputs.md when collecting form factor/style/constraints.
Read references/layout-hygiene.md for screenshot review and layout hygiene decisions.
Read references/page-mapping.md when defining project pages, design surfaces, and bindings.
Read docs/da-vinci-pencli-runtime.md when checking runtime identity, capabilities, MCP, .dvp source, or session flow.
Read docs/design-runtime-gate.md when a PASS/WARN/BLOCK design runtime gate result is blocking progress.
Read docs/design-system-materialization.md when .da-vinci/DESIGN.md must be materialized into runtime variables, themes, or .dvp metadata.
Read docs/icon-system-runtime.md when icon supply, icon map, or .dvp icon application is blocking design.
Read docs/visual-asset-generation.md and docs/manual-visual-asset-pack.md when required visual assets need provider generation, manual packs, import, or replacement.
Read references/da-vinci-pencli-design-to-code.md when turning .dvp design data into implementation.
Read references/platform-adapters.md for Codex/Claude/Gemini invocation patterns.
Read references/skill-workflow-detail.md for stage-specific operational detail moved out of this core file.

The core file is intentionally short. If a rule is stage-specific, it belongs in a referenced owner document, not in the core contract.

name	da-vinci
description	Drive a software delivery workflow from supplement requirements through da-vinci-pencli-backed UI design, task planning, implementation, and verification. Use when product or page work must stay aligned across requirement truth, design truth, and implementation evidence.