@xenonbyte/da-vinci-workflow 0.2.4 → 0.2.6

package/SKILL.md

@@ -29,742 +29,83 @@ That means:
 - treat checkpoints as internal execution guards, not approval steps
 - stop only when a true blocking condition exists
 
-Treat execution intent as `full-delivery` by default when the user asks to:
-
-- complete development
-- implement the generated design
-- redesign the whole product UI
-- finish the project or finish the refresh
-
-Do not stop at `tasks.md` in those cases.
-
-Continue automatically through:
-
-- mode selection
-- project visual-contract detection
-- requirement breakdown
-- page mapping
-- design input collection
-- design source registration
-- Pencil design work
-- page-to-Pencil binding
-- task generation
-- implementation
-- verification
-
-If `tasks.md` exists and the active request is `full-delivery`:
-
-- treat `task checkpoint` as the handoff into implementation, not as an end state
-- start Task Group 1 automatically after a `PASS`
-- start Task Group 1 automatically after a `WARN` unless the warning changes the truth of behavior, source mapping, or permissions
-- do not emit "next recommended step: start Task Group 1" as a terminal outcome
-- instead continue into code changes and report progress by task group
+Treat execution intent as `full-delivery` by default when the user asks to complete/finish development.
+Do not stop at `tasks.md` unless the user explicitly asks for planning-only behavior.
 
 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
+- 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
 
-Do not stop merely because:
-
-- some pages are still out of scope
-- a future follow-up spec may be needed for untouched behavior
-- a project-local `.pen` export is still pending for traceability, unless that missing file would make the active design source ambiguous
-
-Those are warnings unless they prevent safe implementation of the current in-scope work.
-
-## Next-Step Recommendation Discipline
+## Route Discipline
 
-When Da Vinci reports a "next recommended step" or offers route suggestions, make the recommendation stateful rather than listing every possible command as if they were equally valid.
+When Da Vinci reports a “next recommended step”, keep it stateful and singular:
 
-Use this order:
-
-- if discovery or design-source artifacts are still missing, recommend the missing discovery or design work first
+- if discovery or design-source artifacts are missing, recommend discovery/design work first
 - if design is still blocking, recommend `design`
-- if design is ready enough for implementation planning but `.da-vinci/changes/<change-id>/tasks.md` does not exist yet, recommend `tasks`
-- if `tasks.md` exists and `task checkpoint` is at least `PASS` or an explicitly accepted `WARN`, recommend `build`
-- if implementation is already underway or complete enough to check drift, recommend `verify`
+- if design is ready but `tasks.md` does not exist, recommend `tasks`
+- if `tasks.md` exists and task checkpoint is at least `PASS` (or accepted `WARN`), recommend `build`
+- if implementation is underway or done enough to check drift, recommend `verify`
 
 Hard rules:
 
-- do not present `build` as a co-equal next step when `tasks.md` does not exist yet
-- do not present `build` as the primary next step immediately after design completion unless task generation is already done and implementation readiness is clear
-- if design is complete but more in-scope surfaces still need design work, `design` may remain an optional branch, but `tasks` stays the primary next step before `build`
-- if multiple commands are shown, clearly mark only one as the primary next step for the current workflow state
+- do not present `build` as co-equal next step when `tasks.md` does not exist
+- do not present `build` immediately after design completion when task generation is still missing
+- if multiple commands are shown, clearly mark one primary route
 
 ## Invocation Model
 
 Canonical workflow name is `da-vinci`.
 
 - Codex preferred: `$da-vinci <request>`
-- Claude and Gemini preferred: `/da-vinci <request>` when platform adapters exist
-- For Codex helper intents, prefer natural-language patterns:
-  - `$da-vinci use intake for <project situation>`
-  - `$da-vinci use prompt for <known scenario>`
-  - `$da-vinci use continue for <existing workflow state>`
-- Claude and Gemini helper routes remain:
-  - `/dv:intake`, `/dv:prompt`, `/dv:continue`
-- Natural-language invocation remains the default path
-
-## Prompt Entry Routes
-
-Use these helper actions when the user needs help entering or resuming the workflow:
-
-1. `intake`
-   - use when the user describes a project situation but does not know how to phrase the best Da Vinci request
-   - output:
-     - recommended mode
-     - recommended delivery intent
-     - one primary executable workflow prompt
-     - one more conservative prompt when useful
-     - one continuation prompt when the workflow is likely to pause
-     - missing inputs that would materially change the result
-   - `intake` should usually generate a main workflow prompt, not a `build`-only prompt
-
-2. `prompt`
-   - use when the user explicitly asks for a prompt template or scenario-specific prompt
-   - generate one or more copy-ready prompts aligned to the stated scenario
-   - keep prompts operational, not generic advice
-
-3. `continue`
-   - use when workflow artifacts already exist and the user needs to resume
-   - inspect the current artifacts first
-   - output:
-     - detected workflow state
-     - gaps or blockers
-     - one executable continuation prompt
-     - contextual recovery notes from recent checkpoint deltas when consistent with current artifacts
-   - do not restart discovery if the artifacts already provide enough truth
-   - do not default to `build` unless the project is clearly implementation-ready
-   - determine route selection from artifact and checkpoint truth first; contextual deltas are auxiliary and must not override routing
-   - if contextual deltas conflict with current artifacts, ignore them for routing and record the conflict
-
-## V2 Mode Selection
-
-Select one workflow mode before producing artifacts.
-
-Supported modes:
+- Claude/Gemini preferred: `/da-vinci <request>` when adapters exist
+- Helper routes: `intake`, `prompt`, `continue`
 
-1. `greenfield-spec`
-   - use when the project starts from a clear product or page requirement
+`intake` should usually produce a main workflow prompt, not a `build`-only prompt.
+`continue` must inspect existing artifacts first and route from current truth instead of restarting discovery by default.
 
-2. `greenfield-brainstorm`
-   - use when the project starts from multiple rounds of raw ideas and needs synthesis first
+## Supported Modes
 
-3. `redesign-from-code`
-   - use when an existing product already has code and the UI must be redesigned globally or broadly
+Select one mode before producing artifacts:
 
+1. `greenfield-spec`
+2. `greenfield-brainstorm`
+3. `redesign-from-code`
 4. `overhaul-from-code`
-   - use when an existing product needs a broad system-level rewrite where flows, logic, information architecture, and UI may all change
-
 5. `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 `overhaul-from-code` for broad existing-project rewrites where old code is no longer the full behavior truth
-- choose `feature-change` for incremental product work
-
-## Design Input Collection
-
-Before generating new Pencil designs for a greenfield project, collect or infer:
-
-0. project visual contract
-   - detect whether `DA-VINCI.md` already exists
-   - if it exists, treat it as the visual baseline for future pages
-   - if it does not exist, generate it from stable user preferences, existing project signals, or inferred defaults before broad Pencil page generation
-   - if it declares preferred visual adapters, treat them as optional design-assist preferences, not as behavior truth
-
-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. `DA-VINCI.md`
-2. existing workflow artifacts
-3. project-local config or project codebase signals
-4. explicit user answers
-5. short clarification questions
-
-Do not repeatedly ask for inputs that are already stable in the artifacts.
-
-Treat visual adapters as optional design-assist layers.
-
-- resolve them from the user request first, then `DA-VINCI.md`, then locally available skills
-- do not assume cross-platform equivalence between near-name adapters such as `frontend-skill` and `frontend-design`; only resolve adapters that are explicitly named and actually installed in the current environment
-- record which requested adapters were available, which were unavailable, and which adapter became the resolved primary adapter
-- when `DA-VINCI.md` or the request declares `Preferred adapters`, the resolved primary adapter must actively lead first-pass design reasoning instead of being recorded only for traceability
-- when a resolved primary adapter is available, state that runtime resolution explicitly before the first anchor-screen design pass and let it drive the visual thesis, content plan, and interaction thesis
-- use them to improve visual contract quality, composition, hierarchy, spacing, and motion guidance
-- use Pencil guides and platform constraints as buildability aids only; they must not replace the resolved primary adapter as the art-direction source
-- do not let them redefine behavior, page truth, route truth, or acceptance rules
-- if a requested adapter is unavailable locally, continue with native Da Vinci design rules and record the fallback
-
-## Default Workflow
-
-Run the workflow in this order:
-
-1. Select the active mode
-2. Build the correct source artifacts for that mode
-3. Detect or generate `DA-VINCI.md` as the project visual contract
-4. Collect design inputs, prefer project-local `.pen` files under `.da-vinci/designs/`, and register available design sources
-5. Define or discover the project page map
-6. Create or update Pencil designs for the required pages
-7. Bind implementation pages to Pencil pages
-8. Read Pencil design data through MCP
-9. Generate implementation tasks
-10. Implement code from requirements plus Pencil data
-11. Verify behavior drift and design drift before closing the change
-
-Default completion rule:
-
-- if the request is `plan-only`, stop after planning artifacts
-- if the request is `design-only`, stop after design artifacts and bindings
-- otherwise assume `full-delivery` and continue through implementation and verification
-
-Do not report `design complete`, `workflow complete`, or any equivalent terminal state unless the completion gate in `references/checkpoints.md` is satisfied.
-When shell access is available, prefer `da-vinci audit --mode integrity <project-path>` during active workflow work and `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim.
-
-## Pencil Generation Rules
-
-During active Pencil work:
-
-- do not begin anchor-surface generation until the required discovery and design-source artifacts exist in their standard locations for the active mode
-- keep `.da-vinci/designs/` reserved for project-local `.pen` files; do not write workflow markdown such as inventories, proposals, or checkpoints into that directory
-- on `redesign-from-code`, write a short structural-delta note for each anchor surface explaining how the new composition differs from the current XML or layout grouping
-- when shell access is available, preflight non-trivial `batch_design` operation strings before sending them to Pencil
-- prefer 12 or fewer operations on anchor-surface batches; if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
-- do not rely on headless interactive `save()` as the persistence truth; when live MCP edits exist, persist project-local `.pen` files from MCP-readable document snapshots
-- use the session wrapper commands on autonomous runs:
-  `da-vinci pencil-session begin --project <project-path> --pen <path>`
-  `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
-  `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
-- when multiple `.pen` sources exist (for example external backups), run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before a new `pencil-session begin`
-- if baseline hashes diverge, do not treat the previous `persist` success as global freshness; confirm source priority explicitly (`--prefer-source`) and sync the chosen source into the project-local `.pen` before new edits
-- use `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>` when an external source is selected as latest and must be materialized into the project-local baseline
-- before the first Pencil edit on a redesign pass, begin a Pencil session so the registered project-local `.pen` exists before editing and the global Pencil lock is held for that project
-- acquire the global Pencil lock before MCP write operations on a project and release it after the write phase so two projects do not compete for the same active editor
-- when a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to that same path instead of assuming live edits were flushed automatically
-- `da-vinci snapshot-pen` is a disk-to-disk utility for rebuilding an existing `.pen`; do not use it as live-edit persistence
-- use `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open` to atomically write the registered project-local `.pen` from MCP snapshot data
-- after writing the project-local `.pen`, run `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>` before treating the disk source as current
-- completion audit expects a recorded Pencil session state under `.da-vinci/state/pencil-session.json`; do not bypass the session wrapper on autonomous runs
-- after the first successful Pencil write, verify that the registered project-local `.pen` path exists as a shell-visible file before treating the design source as persistent
-- after the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` when shell access is available before broad expansion continues
-- after the first successful Pencil write, run the MCP runtime gate when Pencil MCP is available and record the result in `pencil-design.md`
-- if the workflow already has a registered `.pen`, do not send Pencil write operations with an empty `filePath`
-- do not treat an unnamed live editor such as `new` as a persisted project design source; reconcile it to the registered project-local `.pen` path before the design pass is considered traceable
-- use only Pencil-supported properties; do not emit web- or CSS-only layout properties such as `flex` or `margin`
-- if unsupported Pencil properties cause repeated rolled-back batches on the same anchor surface, treat that pass as unstable and fix the schema usage before expanding further
-- after any rolled-back batch or structure-changing edit, refresh the live node structure before descendant-targeted follow-up operations; do not assume stale ids, bindings, or parent relationships are still valid
-- on complex redesigns, turn approved anchor surfaces into a small shared primitive family before broad page expansion
-- apply the resolved form-factor-specific layout hygiene profile before passing screenshot review on any anchor surface or other approval candidate
-- exported screenshots are review artifacts only; place them under `.da-vinci/changes/<change-id>/exports/` and never treat them as a substitute for the project-local `.pen` source
-- screenshot review is binding: if the review calls out hierarchy, spacing, clarity, inconsistency, or unresolved-placeholder issues, revise the screen before treating the checkpoint as `PASS`
-- screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the concrete issue list and revision outcome; phrases such as "looks good" do not count as review evidence
-- if `DA-VINCI.md` declares `Design-supervisor reviewers`, run an explicit review pass with those reviewer skills on the approved anchor set, then persist the structured result with `da-vinci supervisor-review --project <project-path> --change <change-id> --run-reviewers --write` (or the compatibility alias `design-supervisor review --run-reviewers --write`)
-- keep `Design-supervisor reviewers` separate from `Preferred adapters`; adapters lead the design pass, reviewers judge whether the final style quality is strong enough to expand or implement
-- when `design-supervisor review` is active, review screenshots together with Pencil theme variables, `visual-thesis.md`, `content-plan.md`, and `interaction-thesis.md`; record `Configured reviewers`, `Executed reviewers`, `Review source`, explicit `PASS`/`WARN`/`BLOCK`, issue list, and revision outcome in `pencil-design.md`
-- do not hand-write ad-hoc headings such as `## Design-Supervisor Review (Round X Attempt)`; use `da-vinci supervisor-review --write` (or overwrite the canonical `## Design-Supervisor Review` block) so audit can consume structured evidence deterministically
-- if `DA-VINCI.md` sets `Require Supervisor Review: true`, treat missing, blocked, or unaccepted `design-supervisor review` as a blocker before broad expansion, implementation-task handoff, or terminal completion
-
-## 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/layout-hygiene.md` when screenshot review or the design checkpoint needs form-factor-specific layout hygiene rules
-- 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
-- Read `references/prompt-recipes.md` when generating intake, prompt, or continue helper outputs
-
-## Default Artifacts
-
-Use these artifacts unless the project defines a different schema:
-
-1. `.da-vinci/changes/<change-id>/brainstorm.md`
-2. `.da-vinci/project-inventory.md`
-3. `DA-VINCI.md`
-4. `.da-vinci/changes/<change-id>/design-brief.md`
-5. `.da-vinci/design-registry.md`
-6. `.da-vinci/designs/`
-7. `.da-vinci/page-map.md`
-8. `.da-vinci/changes/<change-id>/proposal.md`
-9. `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
-10. `.da-vinci/changes/<change-id>/design.md`
-11. `.da-vinci/changes/<change-id>/pencil-design.md`
-12. `.da-vinci/changes/<change-id>/pencil-bindings.md`
-13. `.da-vinci/changes/<change-id>/tasks.md`
-14. `.da-vinci/changes/<change-id>/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
-- `DA-VINCI.md`: project-level visual contract for theme, color system, surface treatment, typography direction, and cross-page style rules
-- `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
-- `.da-vinci/designs/`: project-local persisted Pencil sources such as `project-baseline.pen` or change-specific `.pen` files
-- `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
-
-## Artifact Placement
-
-Use this placement model inside the target project:
-
-### Project root
-
-- `DA-VINCI.md`
-
-Keep this file at the project root so the visual contract is easy to discover and reuse.
-
-### Project-level workflow directory
-
-- `.da-vinci/project-inventory.md`
-- `.da-vinci/design-registry.md`
-- `.da-vinci/designs/`
-- `.da-vinci/page-map.md`
-
-These files describe project-wide facts that can outlive any one change.
-
-Recommended `.pen` persistence patterns:
-
-- `.da-vinci/designs/project-baseline.pen`
-- `.da-vinci/designs/<change-id>.pen`
-- `.da-vinci/designs/<change-id>/main.pen`
-
-### Change-level workflow directory
-
-- `.da-vinci/changes/<change-id>/brainstorm.md`
-- `.da-vinci/changes/<change-id>/design-brief.md`
-- `.da-vinci/changes/<change-id>/proposal.md`
-- `.da-vinci/changes/<change-id>/design.md`
-- `.da-vinci/changes/<change-id>/pencil-design.md`
-- `.da-vinci/changes/<change-id>/pencil-bindings.md`
-- `.da-vinci/changes/<change-id>/tasks.md`
-- `.da-vinci/changes/<change-id>/verification.md`
-- `.da-vinci/changes/<change-id>/specs/<capability>/spec.md`
-
-These files belong to one concrete delivery effort and should not clutter the project root.
-
-## Mode-Specific Artifact Flow
-
-Use these minimum flows:
-
-### `greenfield-spec`
-
-`DA-VINCI` -> `.da-vinci/changes/<change-id>/design-brief` -> `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/design` -> `.da-vinci/changes/<change-id>/pencil-design` -> `.da-vinci/changes/<change-id>/pencil-bindings` -> `.da-vinci/changes/<change-id>/tasks` -> `.da-vinci/changes/<change-id>/verification`
-
-### `greenfield-brainstorm`
-
-`.da-vinci/changes/<change-id>/brainstorm` -> `DA-VINCI` -> `.da-vinci/changes/<change-id>/design-brief` -> `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/design` -> `.da-vinci/changes/<change-id>/pencil-design` -> `.da-vinci/changes/<change-id>/pencil-bindings` -> `.da-vinci/changes/<change-id>/tasks` -> `.da-vinci/changes/<change-id>/verification`
-
-### `redesign-from-code`
-
-`.da-vinci/project-inventory` -> `DA-VINCI` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` -> `.da-vinci/changes/<change-id>/design` -> `.da-vinci/changes/<change-id>/pencil-design` -> `.da-vinci/changes/<change-id>/pencil-bindings` -> `.da-vinci/changes/<change-id>/tasks` -> `.da-vinci/changes/<change-id>/verification`
-
-For broad refreshes, treat `.da-vinci/changes/<change-id>/specs/` as a redesign-slice directory, not as a single-file location.
-
-### `overhaul-from-code`
-
-`.da-vinci/project-inventory` -> `.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/migration-contract` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` -> `DA-VINCI` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/design-brief` -> `.da-vinci/changes/<change-id>/design` -> `.da-vinci/changes/<change-id>/pencil-design` -> `.da-vinci/changes/<change-id>/pencil-bindings` -> `.da-vinci/changes/<change-id>/tasks` -> `.da-vinci/changes/<change-id>/verification`
-
-For broad overhauls, treat `.da-vinci/changes/<change-id>/specs/` as an overhaul-slice directory and keep `migration-contract.md` singular for preserve/revise/retire decisions.
-
-### `feature-change`
-
-`.da-vinci/changes/<change-id>/proposal` -> `.da-vinci/changes/<change-id>/specs` -> `.da-vinci/page-map` for affected pages -> `DA-VINCI` -> `.da-vinci/design-registry` -> `.da-vinci/changes/<change-id>/design` -> `.da-vinci/changes/<change-id>/pencil-design` delta -> `.da-vinci/changes/<change-id>/pencil-bindings` delta -> `.da-vinci/changes/<change-id>/tasks` -> `.da-vinci/changes/<change-id>/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
-- treat existing code as behavior truth and implementation-surface discovery, not as a visual-layout baseline
-- default to fresh visual composition unless the user explicitly asks to preserve the current layout skeleton
-- partition specs by redesign slice when one oversized `ui-refresh` spec would hide important implementation boundaries
-
-If the active mode is `overhaul-from-code`:
-
-- inventory current routes, pages, modules, key flows, integrations, and permission boundaries before redefining the target product
-- treat existing code as reference evidence and migration baseline rather than the final target behavior truth
-- classify current system areas into `preserve`, `revise`, `retire`, and `unknown` in `migration-contract.md`
-- stabilize new `proposal.md` and `specs/` before broad Pencil design or implementation
-- update `page-map.md` to reflect the new target page set, not only the old route tree
-- route verify failures back to `migration-contract.md`, `page-map.md`, or specs when overhaul truth is still unstable
-
-## Spec Partitioning Rules
-
-Do not default to one oversized `ui-refresh` spec for broad redesign work.
-
-For `redesign-from-code`:
-
-- keep one overall `proposal.md`
-- keep one project-level `DA-VINCI.md`
-- keep one project-level `project-inventory.md`
-- keep one project-level `design-registry.md`
-- keep one project-level `page-map.md`
-- split `specs/` by redesign slice when the refresh is broad
-
-Preferred redesign slices:
 
-- `shared-shell`
-- `core-pages`
-- `settings-and-secondary`
-- `admin-or-restricted`
-- `reference-gap-pages`
+If user input does not specify a mode, infer from project reality:
 
-Split broad redesign work into multiple spec slices when one or more of these are true:
+- new clear requirements -> `greenfield-spec`
+- exploratory ideation -> `greenfield-brainstorm`
+- broad UI replacement on existing code -> `redesign-from-code`
+- broad existing-project rewrite of flows/logic/IA/UI -> `overhaul-from-code`
+- scoped incremental change -> `feature-change`
 
-- the refresh covers more than five canonical pages
-- the refresh spans more than two top-level route groups or page families
-- the redesign includes both shared-shell changes and page-content changes
-- prior HTML or Pencil references cover only part of the product surface
-- different page groups carry different layout, density, or access constraints
+## Design-Supervisor Gate
 
-One redesign spec is acceptable when the refresh is mostly cosmetic, narrow, or limited to a small product surface.
+Core contract reminders:
 
-Do not split page-by-page unless the product is unusually fragmented. Prefer implementable redesign slices over raw page counts.
+- `Design-supervisor reviewers` are reviewer gates, not visual adapters.
+- reviewer configuration and `design-supervisor review` evidence must remain explicit in workflow artifacts.
+- when supervisor review is required, missing/blocked/unaccepted review is a blocker before terminal completion.
 
-For `overhaul-from-code`:
-
-- keep one overall `proposal.md`
-- keep one `migration-contract.md`
-- keep one project-level `DA-VINCI.md`
-- keep one project-level `project-inventory.md`
-- keep one project-level `design-registry.md`
-- keep one project-level `page-map.md`
-- split `specs/` by overhaul slice when the rewrite spans multiple implementation or migration boundaries
-
-Preferred overhaul slices:
-
-- `shell-and-navigation`
-- `core-flows`
-- `account-and-settings`
-- `legacy-migration`
-- `admin-or-restricted`
-
-## Design Source Rules
-
-Use `design-registry.md` as the project-level inventory of `.pen` sources.
-
-Use `.da-vinci/designs/` as the default project-local location for persisted Pencil files when the workflow creates or updates them.
-
-Treat the project-local `.pen` path recorded in `design-registry.md` as workflow-owned state.
-
-- users may provide external references or existing `.pen` files
-- the workflow, not the user, resolves and maintains the preferred project-local `.pen` path
-- do not treat `design-registry.md` as a user-authored config file
-
-Resolve one exact project-local target before broad Pencil work begins:
-
-- `.da-vinci/designs/project-baseline.pen` for shared baseline reconstruction
-- `.da-vinci/designs/<change-id>.pen` for change-specific redesign work
-- `.da-vinci/designs/<change-id>/main.pen` only when the project truly needs a nested design bundle
-
-Use `DA-VINCI.md` as the project-level visual source of truth for:
-
-- theme and palette
-- background and surface treatment
-- typography direction
-- component tone
-- rules for cross-page consistency
-- optional visual adapter preferences
-
-Treat visual adapters as optional helpers for presentation quality only.
-
-- they may refine `DA-VINCI.md`, `design.md`, and `pencil-design.md`
-- they must not override behavior truth from requirements or existing code
-- they must not replace `page-map.md`, `design-registry.md`, or `pencil-bindings.md`
-
-When a relevant mapping already exists:
-
-- iterate on the mapped Pencil source
-- prefer the project-local `.pen` file under `.da-vinci/designs/` when one is already registered
-- do not create a new design baseline unless there is a reason
-- do not silently keep designing in an unrelated active Pencil document when `design-registry.md` already names a preferred path
-
-When `DA-VINCI.md` already exists:
-
-- use it as the baseline visual contract
-- do not regenerate visual direction from scratch unless the change explicitly rebrands or resets the product style
-- if it declares preferred visual adapters, try to resolve them without blocking the workflow
-
-When page-to-Pencil bindings already exist:
-
-- update the mapped Pencil page for the affected implementation page
-- keep the exact `.pen` file path recorded in `design-registry.md`
-- if the active Pencil editor path differs from that recorded path, switch to the recorded path or explicitly reconstruct the project-local file before continuing
-
-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`
-- resolve the exact project-local `.pen` target path before broad Pencil work starts
-- generate a new Pencil baseline only after the inventory is stable
-- materialize that baseline into the resolved `.da-vinci/designs/` path and record the exact file in `design-registry.md`
-
-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
-- generate `DA-VINCI.md` from inferred or user-provided design rules before generating many unrelated pages
-- persist the resulting `.pen` file at the resolved `.da-vinci/designs/` path and record that exact path in `design-registry.md`
-
-When a Pencil session cannot yet be exported locally:
-
-- record the live or external source in `design-registry.md`
-- reconstruct and write the project-local `.pen` file from MCP-readable document data before closing mapping or implementation work
-- if the project-local file still cannot be materialized, record the reason and treat the missing file as a checkpoint issue instead of silently continuing
-
-When visual adapters are requested:
-
-- resolve them from local availability when possible
-- choose one primary adapter when multiple helpers are available
-- record the requested adapters, resolved primary adapter, any secondary helpers, and fallback status in `design-registry.md`
-- treat the resolved primary adapter as the design lead for the first Pencil pass, especially on anchor screens and quality-critical surfaces
-- if `Require Adapter: true` and the requested adapter is unavailable, treat that as a blocker instead of silently downgrading the visual bar
-- continue with native Da Vinci design rules when no adapter is available unless the user explicitly requires a specific adapter
-
-If the request is too vague to design or implement safely, ask a short clarification question before generating artifacts.
-
-## Surface Decomposition Rules
-
-Do not treat one implementation container as one design surface by default.
-
-For complex products, decompose by:
-
-- canonical page
-- subpage
-- state
-- overlay
-- shared shell region
-- implementation surface such as activity, fragment, tab, bottom sheet, dialog, or full-screen mode
-
-When an Android screen contains multiple fragments, tabs, nested flows, or materially different states:
-
-- split them into distinct design surfaces in `page-map.md`
-- give each meaningful state or subpage its own Pencil target when the layout materially changes
-- avoid collapsing them into one overloaded redesign screen
-
-One implementation page may legitimately map to:
-
-- multiple Pencil screens
-- multiple states of one Pencil page
-- one shared shell plus several detail surfaces
-
-Treat surface decomposition as required when visual structure changes materially across states or subflows.
-
-## 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
-- use the workflow-owned `.pen` path from `design-registry.md` as the active design target
-- do not keep designing in whichever Pencil document happens to be open unless it already matches the registered project-local path
-- use the resolved visual adapter, when available, for composition, hierarchy, restraint, and motion guidance
-- on complex redesigns, design only 1-3 anchor surfaces first before broad multi-screen generation
-- make each anchor surface fully composed with real hierarchy and content structure before expanding the rest of the product
-- before broad page generation, write a visual thesis, a content plan, and an interaction thesis for the current surface
-- use screenshot review after each anchor surface and revise before cloning or expanding variants
-- 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
-- Reject generic UI patterns such as dashboard-card mosaics, weak visual anchors, decorative clutter, or motion with no hierarchy value
-- reject placeholder-heavy scaffolds; unresolved placeholder rectangles are not acceptable substitutes for real screen composition
-- For `redesign-from-code`, redesign from page responsibilities and state decomposition, not by recoloring or slightly rearranging the old UI
-- After changes, inspect the result visually before treating it as implementation-ready
-
-When multiple pages exist:
-
-- derive the remaining pages from approved anchor surfaces and shared primitives rather than from an empty repeated template
-- 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`
-- ensure the active Pencil design is materialized into the registered `.da-vinci/designs/` file before closing design work
-
-## Pencil MCP Rules
-
-When Pencil is available through MCP:
-
-- Prefer the project-local `.pen` file under `.da-vinci/designs/` when one is registered
-- Treat the registered `.pen` path as authoritative; do not rely on the current active editor if its path does not match `design-registry.md`
-- If the registered file exists, read and edit that exact file
-- If the registered file does not yet exist, create or reconstruct the project-local file before treating the design pass as traceable
-- 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
-- Before mapping or implementation closes, verify both:
-  - the `.pen` path is readable through MCP
-  - the same path exists as a shell-visible file inside the project
-- Before broad expansion or terminal completion, run the MCP runtime gate:
-  - evaluate source convergence from the active editor, registered `.pen` path, and shell-visible `.pen` file
-  - evaluate screen presence for claimed anchor and review target ids
-  - evaluate review execution for approved surfaces
-  - append the runtime gate result to `pencil-design.md`
-
-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. `design-source checkpoint`
-   - after `design-registry.md` resolves the preferred project-local `.pen` path and active Pencil work exists
-   - verify the registered `.pen` path, the active Pencil editor, and shell-visible persistence agree before mapping continues
-
-5. `mapping checkpoint`
-   - after `design-registry.md` and `pencil-bindings.md`
-   - verify implementation pages and Pencil pages are bound correctly
-
-6. `task checkpoint`
-   - before implementation starts
-   - verify tasks cover both requirements and Pencil-backed UI work
-
-7. `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
-- contextual-delta issues: warn and continue; do not treat missing/stale contextual notes as standalone blockers
-
-## 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
+## Load References On Demand
 
-After meaningful work, report:
+Load only the reference that matches the active stage:
 
-1. changed files
-2. active mode
-3. current workflow state
-4. next recommended step
-5. blockers or drift
+- Read `references/modes.md` when selecting or explaining a workflow mode.
+- 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, Pencil pages, and bindings.
+- Read `references/pencil-design-to-code.md` when turning Pencil data into implementation.
+- Read `references/platform-adapters.md` for Codex/Claude/Gemini invocation patterns.
+- Read `references/prompt-recipes.md` for `intake`/`prompt`/`continue` helper output generation.
+- Read `references/skill-workflow-detail.md` for stage-specific operational detail moved out of this core file.
 
-Keep updates concise and operational.
-Make `next recommended step` follow the state rules above; do not list `build` next to `tasks` as if they were equivalent when task generation has not happened yet.
+The core file is intentionally short. If a rule is stage-specific, it belongs in a referenced owner document, not in the core contract.