stitch-delivery-harness

Stitch Editable Design Delivery

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

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 for the next item."
"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 one-off lightweight edit, use the corresponding single-operation Skill.

Capability Boundaries

✅ Good At

Completing delivery of the Stitch original draft, or completing a high-fidelity closed loop between Stitch and ImageGen after the user has explicitly chosen to do so.
Verifying HTML, dimensions, copy, business rules, and editability.
Generating comparison evidence and archiving after approval.

⚠️ Requires Materials 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.
Only generating a page once without requiring a delivery closed loop: use the Generate Screen Skill.
Publishing without authorization, 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 a starter spec that does not exist, 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 passes acceptance, the Harness must stop at AWAITING_ART_DECISION, and present each item to the user:enhance(second 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 original text be passed to art-decision --user-response; ambiguous replies such as "confirm", "continue", "do it", or "okay" must continue to be followed up on, 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 a real Stitch, ImageGen, OCR, or visual evaluation tool, use stitch_harness.evidence_writer.EvidenceWriter 's corresponding type method to generate evidence, then call resume --evidence。
selection enhance After choosing, perform two-image comparison python scripts/setup_harness_runtime.py run compare ...; the input may only be derived from the current run's imagegen and roundtrip receipts. When choosing keep_stitch , do not call ImageGen, and directly perform a reversible edit probe on the accepted Stitch HTML/render.
provider_generated Strictly verify the Provider device and scaling;imported_editable_html still requires a real render artifact that exactly matches the spec canvas. If OCR reports any observed_text_drift , it fails. Before roundtripping the enhanced branch, stitch.normalize must be generated data-purpose receipt, only allowing the declared one-to-one replacement.
If not converged, it can be redone: after the user rejects the candidate draft at AWAITING_USER_APPROVAL , the run may proceed via ART_GENERATED by redo_art(only enhance) return to the art enhancement to begin a new round; each round counts toward delivery_rounds, with an upper limit of the specification's comparison.max_rounds(default 3); when exhausted, enter BLOCKED and retain all evidence; do not extend rounds on your 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 repair 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 scoring axis is missing 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 hand back to the user, consuming no more rounds.
Attribution must be truthful: visual evidence records the real judge's provider/model and must not be recorded as a local deterministic tool; deterministic layout scores must separately annotate the algorithm name and version, and be 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, reconcile only with project/screen read tools, do not resend directly; after the read probe forms evidence, execute reconcile --evidence; if still unknown after three times, switch to BLOCKED。
BLOCKED only those with an explicit reason recover --reason "..." can recover; ordinary resume must not bypass.
Dimensions use the page specification's content canvas, not the browser outer frame or device pixel ratio.
After backfill, the HTML and render image must be downloaded again, and probe editing and recovery must be 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 missing, you must stop at AWAITING_ART_DECISION。
After all automated gates pass, you may only enter AWAITING_USER_APPROVAL。
Show the user the final Stitch render, the art draft, and a side-by-side comparison image at the same time; without explicit approval, do not call approve or archive。
Credentials are passed to the local stdio proxy only via the current process or restricted user configuration; do not read, print, or write them to evidence.

Stop conditions

When the status is BLOCKED, an 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, gates passed, gates failed, and the next required evidence.

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

Customizable content comes from the page specification: canvas, theme, fixed copy, editable areas, business assertions, visual thresholds, and archive locations. Do not silently rewrite the specification during a run.

FAQ

No page specification? First create one and have the user confirm the specification; do not start a run.

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

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

Can OCR approval be granted? 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 first verifying the desktop login page, read WeKefu Login Sample。

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 execute 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 output are missing, clearly mark them as NOT_VERIFIED。
Idempotency first: retain the request identifier and stage state; when the result is unclear, query first rather than blindly retrying.
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 off to a more precise skill.

Step 2: Perform pre-checks

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 change, the success criteria and the safe exit method after failure.

Step 4: Execute actions

Execute with the minimum sufficient steps and record evidence at key state changes; retain a correlatable 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 adjacent tasks were not misrouted to this skill.
The inputs, target objects, versions and output locations are all clear, and no guessed values were used to replace required values.
All write, paid, publish or irreversible actions are within the user's authorization scope.
The results have been verified with independent checks; only "command succeeded" or "file exists" does not count as complete acceptance.
The output includes actual evidence, failed/skipped items, remaining risks and executable next steps.

Gotchas

Treating the plan as the result: Documents or prompts are not equal to actual execution; the actual execution level must be indicated.
Error retry: A timeout or lost response may already have produced remote state; query first before deciding whether to retry.
Implicit scope expansion: Batch, full-scale, publish, overwrite, and paid operations are not natural extensions of ordinary reads and writes.
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; writes, payments, publishing, and irreversible actions require explicit authorization. If the request requires another skill, do not copy its body; hand off by skill name and preserve the current task context.

Progressive disclosure

When input/output, state, 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 timeout, partial success, or recovery scenarios, read references/error-recovery.md。
For first run, refusal of overreach, and failure recovery, refer respectively to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。