Upgrade Site

Upgrade Site (Orchestrator)

You own scope, synthesis, sequencing, and verification. design-dna observes and abstracts; it never implements. motion-craft implements against blueprints; it never researches references. All handoffs are Markdown artifacts beneath the target repository, and all implementation is constrained by the target project's own architecture and route policies.

Authority modes

audit      Snapshot, research, report only.        (explicit "audit")
plan       Audit + written upgrade plan.           (DEFAULT — vague requests
                                                    like "make it look better")
implement  Plan + modify code + verify.            (explicit only: "implement",
                                                    "run the full pipeline")

What each mode may write:

audit:      evidence + audit report only. May NOT modify application source,
            dependencies, configuration, or design docs.
plan:       + blueprints, synthesis, plan documents, MOTION.md policy seed.
            May NOT modify application source, dependencies, runtime config.
implement:  may modify approved source and configuration.

The audit/plan restriction is on source mutation, not filesystem writes — artifacts beneath the contract paths are always permitted for the mode that produces them. Never auto-edit .gitignore; recommend entries instead.

Target resolution

target_repo = explicit path → current git root → cwd

Canonicalize; refuse / or $HOME; all writes beneath the target; log the resolved target and chosen mode before doing anything else.

Pipeline

1. Snapshot key pages (home + 2–4 representative templates) × viewports 390×844 and 1440×900 → .artifacts/site-upgrade/<run-id>/baseline/. If the target's HEAD materially differs from the deployed site, snapshot a local build; otherwise the production site is an acceptable baseline. Record which was used.

2. References — invoke design-dna (research mode unless URLs given).

3. Synthesize → <target_repo>/design-dna/synthesis.md covering: shared patterns; meaningful disagreements; which reference leads each dimension; combinations that must not be mixed; recommended direction for the target; patterns rejected for brand/content fit.

4. Gap analysis — score the target vs the synthesis, 0–10 per dimension: typography, color, layout, imagery, motion, brand fit — each with "what would make it a 10".

   0–2 absent/harmful · 3–4 inconsistent/unfinished · 5–6 competent baseline
   7–8 distinctive and coherent · 9 exceptional · 10 reference-quality (rare)
   

   Accessibility and performance are gates, not tradable dimensions — no visual ambition may lower either below the current baseline. Record the scores and each "what would make it a 10" in the plan document (or the audit report in audit mode).

5. Plan → <target_repo>/docs/plans/ following the target's existing naming conventions. Order: quick wins → signature moments. Include the project-policy seed for docs/MOTION.md: excluded high-volume templates, animation-eligible surfaces, locale list. Write the seed as a PLAIN section at the top of docs/MOTION.md, above any motion-craft managed sections; once written it belongs to the project (motion-craft never edits content outside its managed markers).

6. Dispatch (implement mode only) — motion items → motion-craft (inherits implement authority); static design items → the project's build skills (e.g. editorial-designer / frontend-design) following the plan.

7. Close — re-snapshot changed pages, run a design-review pass if that skill is available, and complete motion-craft's verification gates.

Git safety (implement mode)

Same rules as motion-craft: target must be a git repo; stop on a dirty tree with unrelated changes; prefer a dedicated branch; commit only when the worktree was clean and gates passed — otherwise leave changes uncommitted with a proposed commit breakdown.

Failure behavior

A blocked reference, missing browser tooling, or an unavailable sub-skill degrades the run (partial blueprint, N/A evidence, deferred items with rationale) — it never halts the pipeline waiting for input in a non-interactive run.