stitch-design-harness

Stitch Design Delivery Orchestration

Treat page delivery as a finite, recoverable evidence process. General state is managed by the plugin Harness; business projects only store specs, artifacts, receipts, and approval archives. Completion must not be marked based on tool success text.

Name and Historical Task Compatibility

This skill was renamed from stitch-delivery-harness . Old handler names in historical run/dispatch are resolved only as compatible names for this entry point; the original packet's run_id, dispatch_id, handler, scope, and evidence_stage are preserved, historical records are not modified, and no new run is created.stitch_harness.py, the run directory, and the existing evidence format remain as they are.

Quick Start

"Turn the confirmed Stitch login page into an editable HTML and artwork draft closed loop."
"Continue this Harness run, and first tell me what evidence is missing next."
"Compare the roundtripped Stitch page with the ImageGen draft, and do not archive before approval."

Suitable for product, design, and frontend teams that need deliverable designs; when you only want to query a Stitch project or make a lightweight edit, use the corresponding single-operation Skill.

Capability Boundaries

✅ Good At

Completing Stitch original draft delivery, or completing the Stitch and ImageGen high-fidelity closed loop after the user explicitly chooses it.
Verifying HTML, dimensions, copy, business rules, and editability.
Generating comparison evidence and archiving after approval.

⚠️ Requires Assets or Capabilities

Page specs and design language.
Available Stitch, ImageGen, OCR, and visual evaluation tools.
The user's explicit approval of the final candidate draft.

❌ Not Applicable

Simply querying a project or screen: use the Stitch read Skill.
Generating a page only once and not requiring a delivery closed loop: use the generate screen Skill.
Unauthorized publishing, deleting a remote project, or approving on behalf of the user: stop and explain the required authorization.

Entry

Fully read the project's .stitch/specs/<page-id>.json。

Locate the plugin root directory two levels up from this Skill, and call:

python /absolute/plugin/root/scripts/stitch_harness.py spec init --project /absolute/project --page-id page-id
python /absolute/plugin/root/scripts/stitch_harness.py start --project /absolute/project --spec page-id

spec init Only create the starter spec if it does not exist, and never overwrite an existing spec; after user confirmation, then start。
For an existing run use status or resume, and do not recreate the run.
After the Stitch original draft is accepted, the Harness must stop at AWAITING_ART_DECISION, and present to the user item by item:enhance(secondary image generation),keep_stitch(keep the Stitch original draft), or cancel(cancel), then end the current execution and wait for a new reply. Only when the user's new reply is strictly equal to one of the canonical values may that exact text be passed to art-decision --user-response; ambiguous replies such as "confirm", "continue", "do it", or "okay" must continue to be clarified, and must not be chosen on the user's behalf, translated, synonym-mapped, or inferred from old messages.
Only execute what the Harness returns next_action; after calling real Stitch, ImageGen, OCR, or visual evaluation tools, use the corresponding type method of stitch_harness.evidence_writer.EvidenceWriter to generate evidence, then call resume --evidence。
After selecting enhance , for dual-image comparison execute python scripts/setup_harness_runtime.py run compare ...; the input can only be derived from the current run's imagegen and roundtrip receipts. When selecting keep_stitch , do not call ImageGen, and directly perform a reversible editing probe on the accepted Stitch HTML/render.
provider_generated Strictly verify the Provider device and scaling;imported_editable_html A real render artifact fully consistent with the spec canvas is still required. OCR reports any observed_text_drift fail. Before backfilling the enhancement branch, a stitch.normalize receipt must be generated, and only the declared data-purpose one-to-one replacement is allowed.
Non-convergence allows redo: after the user rejects a candidate draft in AWAITING_USER_APPROVAL , the run may, via ART_GENERATED , by redo_art(only enhance) return to the art enhancement start for a new round; each round counts toward delivery_rounds, with an upper limit of the spec's comparison.max_rounds(default 3); upon exhaustion enter BLOCKED and retain all evidence; rounds must not be expanded on one's own.
Visual scoring is produced by an independent judge: five axes hierarchy/density/color/component_quality/completion , each scored 1-5 (one decimal place allowed), accompanied by a gap list with stable IDs (including attributable descriptions and remediation directions). The judge must be in a fresh context, independent of the executor being scored, and subject to the anti-ratchet rule (no obligation to raise scores; regressions must be given lower scores). If a score is missing an axis or out of range, the comparison step fails fast and produces no submittable evidence.
Stagnation determination: when the total five-axis score improves by less than 1 point for two consecutive rounds, or the same gap ID appears for two consecutive rounds, the next round's redo_art must declare a structural redo; if still stagnant after the structural redo, stop and return to the user without consuming further rounds.
Attribution truthfully: visual evidence must record the real judge's provider/model and must not be recorded as a local deterministic tool; deterministic layout scores must be separately labeled with algorithm name and version and displayed separately from judge scores. No automated gate or judge score may replace explicit user approval.

Hard gates

Stitch write timeout or unknown receipt: enter RECONCILING, use only project/screen read tools to reconcile, do not directly resend; after the read probe forms evidence, execute reconcile --evidence; if still unknown after three times, switch to BLOCKED。
BLOCKED Only a recover --reason "..." with an explicit reason can recover; ordinary resume must not bypass it.
Dimensions are taken from the page spec's content canvas, not the browser outer frame or device pixel ratio.
After backfilling, the HTML and render image must be re-downloaded, and probe editing and recovery completed.
Do not trust edit_screens 's success text; semantic corrections must pass deterministic local normalization, HTML upload, and hash/DOM verification after re-download.
SOURCE_ACCEPTED does not authorize ImageGen; when an explicit user art decision is lacking, stop at AWAITING_ART_DECISION。
After all automated gates pass, only enter AWAITING_USER_APPROVAL。
Show the user the final Stitch render, the artwork draft, and the side-by-side comparison at the same time; without explicit approval, do not call approve or archive。
Credentials are handed to the local stdio proxy only via the current process or a restricted user configuration; do not read, print, or write them to evidence.

Stop conditions

Status is BLOCKED, the unknown write has not yet been reconciled, the three-round limit is reached, a real tool receipt is missing, or user approval is awaited: stop immediately and return the current run ID, passed gates, failed gates, and the next required evidence.

When information is insufficient, first perform a read-only status, give the current status and missing items based on the existing spec; do not guess resource IDs, dimensions, copy, or approval results. Multi-page requests are executed page by page in the approved backlog order; if one page is not complete, do not concurrently archive the next page.

Customizable content comes from the page specification: canvas, theme, fixed copy, editable regions, business assertions, visual thresholds, and archival location. The specification must not be silently rewritten during a run.

FAQ

No page specification? Create it first and have the user confirm the specification; do not start the run.

If the tool says success, can you continue? No; you must download the file and verify the hash and the corresponding gate.

What if a write operation times out? Save unknown, enter explicit RECONCILING, read-only reconciliation; if unresolved after three times, switch to BLOCKED, and do not blindly retry.

Can OCR passing be approved? No; OCR is only an automated gate.

Can the final image be moved directly? Yes, but the old session path must retain a relative symlink and the hash must be verified.

How should sensitive data be handled? Use demo data; evidence must not store Keys, Cookies, Headers, base64, or signed URLs.

Reference as needed

When executing or resuming the complete closed loop, read workflow。
When creating external tool receipts, read evidence contract。
When encountering error recovery or edge cases, read anti-patterns and deep FAQ。
When verifying the desktop login page for the first time, read WeKefu login sample。

When to use (when to use)

Load this skill when the user needs to select and execute a verifiable, recoverable professional workflow for the current request . First extract the goal, inputs, constraints, delivery format, and acceptance criteria from the request; the description summary is: Use when a Stitch screen must become a complete high-fidelity delivery with editable HTML, art enhancement, verification, user approval, and traceable archival..

Rules

Read before write: first confirm the current state and real capabilities, then perform actions that change external state.
Least privilege: use only the files, tools, accounts, and network scope required to complete the current step.
Evidence first: when run results, resource IDs, versions, hashes, or test outputs are missing, clearly mark them as NOT_VERIFIED。
Idempotency first: retain the request identifier and stage state; when the result is unclear, query first and do not blindly retry.
Privacy and security: logs, examples, receipts, and error messages must not contain tokens, cookies, keys, or personally sensitive data.

Workflow

Step 1: Clarify intent

Confirm whether this skill matches the goal; if it is only an adjacent need, hand it to a more precise skill.

Step 2: Run prechecks

Confirm the goal, inputs, constraints, available tools, success criteria, and failure boundaries; if any key condition is unknown, stop at the read-only stage.

Step 3: Form a plan

List the tools to be called, the objects that will be changed, the success criteria, and the safe exit method after failure.

Step 4: Execute actions

Execute in the minimum sufficient steps, and record evidence at key state changes; retain an associable state or receipt for every external call.

Step 5: Verify delivery

Output the results, verification evidence, unfinished items, risks, and clear next steps, and state facts, inferences, and unverified items separately.

Validation checklist

The skill trigger conditions are consistent with the user's intent, and no adjacent task was misrouted to this skill.
Inputs, target objects, versions, and output locations are all clearly defined, and no required values have been replaced with guesses.
All write, paid, publishing, or irreversible actions are within the scope of user authorization.
Results have been verified with independent checks; only "command succeeded" or "file exists" does not count as complete acceptance.
Output includes actual evidence, failed/skipped items, remaining risks, and executable next steps.

Gotchas

Treating a plan as a result: documentation or prompts are not equivalent to actual execution; the actual execution level must be indicated.
Retrying on error: a timeout or lost response may already have produced remote state; query first before deciding whether to retry.
Implicit scope expansion: batch, full-scale, publishing, overwriting, and paid operations are not natural extensions of ordinary read/write operations.
Version drift: when referencing external resources, record the version, tag, or commit; do not treat a mutable branch as release evidence.
Stale evidence: caches, old screenshots, and historical tests cannot prove the current environment; refresh key evidence before delivery.

Non-applicability and boundaries

Do not exceed the scope given by the user; write, paid, publishing, and irreversible actions require explicit authorization. If the request requires another skill, do not copy its content; hand off by skill name and preserve the current task context.

Progressive disclosure

When inputs/outputs, status, and authorization points need to be determined, read references/workflow-contract.md。
When pre-delivery self-check is needed, read references/validation-checklist.md。
When encountering timeouts, partial success, or recovery scenarios, read references/error-recovery.md。
For first run, refusal of privilege escalation, and failure recovery, refer to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。