Design Harness

Workflow

0. Discover the workspace (the first step on every trigger). Order: a path the human gives > the .design-harness/config.json registry > the default docs/design-harness/. More than one candidate, or zero: ask — never initialize a new workspace silently (init in the wrong place forks the truth). The canvas path follows the same rule: whichever of the two locations the registry is missing — the workspace, or the "canvas" key — is asked as an option picker, one prompt when both are missing; canvas options are docs/canvas.html (keeps zero-workflow GitHub Pages open: that mode serves only / or /docs) and beside-the-workspace; record the choice under the registry's "canvas" key. Only the bootstrap writes the registry; on finding a workspace the registry missed, re-run the bootstrap to record it. A fresh bootstrap ends by asking the human for the target (purpose and acceptance criteria, in the human's words) — transcribe the answer into target.md, never invent one; the human may defer. Scripts run at the host project root (<skill-dir> is wherever this skill is installed):

   python3 <skill-dir>/scripts/discover_workspace.py          # prints which workspace resolves
   python3 <skill-dir>/scripts/init_workspace.py <workspace>  # bootstrap: skeleton + registry + both validators

1. Ingest evidence: file source cards, grade, anchor to provenance; source disagreements go on the board as-is.

2. Transcribe judgments: judgments the human voices in conversation transcribe into idea cards automatically; same-judgment cards merge automatically, conflicts go on the board for the human to pick; derive references and tag classification (one pass — both are relationship reads).

3. Sync (on the human's command, never automatic): idea → output re-derivation runs only when the human orders it — apply directly with a one-line receipt, a diff first for large changes; re-derive the affected elements, never rewrite the whole document. A human edit to output is itself an adjudication: back-transcribe it into idea cards automatically (transcription only). Target changes follow the same discipline as idea changes. When output lags you may hint once ("output is N ideas behind"), never twice.

4. Assemble: first assembly is human-initiated; the form comes from target.md + the output-forms library — when the human sets a target, recommend a form from the library; if target.md is still blank when assembly is called for, ask for the target once more before recommending; the first is system-design (mermaid diagrams are the markdown body itself, plus a modules/ layer, one module per file). Anchor every output claim to evidence; write principles as bullet lists, one principle per bullet — so each can be referenced, edited, and ledgered on its own; in the system-design form the diagram IS the markdown body: mermaid blocks carry click declarations into module files.

5. Project and deliver: whenever the truth changes, regenerate the touched layers' indexes, rebuild the canvas, and republish in the same turn; append the ledger.

   python3 <skill-dir>/scripts/build_canvas.py <workspace> -o <temp-dir> [--css …] [--title '…']

   Without <workspace> the tool discovers on its own (registry → default location) and refuses to act on ambiguity. -o takes a directory (the file lands inside as canvas.html) or a .html path written as-is. Build targets are the fixed canvas.html beside the workspace — commit it when the workspace lives in git, so whoever gets the repo gets the board — or a temp dir or artifact for throwaway views; the builder refuses to write inside the workspace either way. A build is not delivered until the human holds a clickable link. The product is one fully self-contained HTML file (all dependencies inlined, zero network requests). The default delivery is a published HTML link: publish as an artifact or the host's hosted pages (GitHub Pages recipe) and hand over that URL; in Claude Code (a local CLI session) a local link suffices — an absolute file://…/canvas.html URL or a local static server. Every rebuild reuses the existing link — mint a new one only when the human asks. So the link survives the session: record the delivery target — the HTML output path or the published link — under a "canvas" key in the .design-harness/config.json registry, and read it back before building; later sessions then rebuild the same file and republish the same link.

Teach in place, never lecture

• First contact (the workspace just bootstrapped, whether the skill fired passively or on demand): the first move is always to build the workspace, construct the initial canvas in the same turn, hand over the link, then orient in one sentence — "From now on every resource we look into files itself, and the decision judgments we talk through land on the board; you can also just ask me to change things, and tell me whenever you want the design assembled." Never repeat it.
• The workspace is young, no output yet: leave the assembly seat visibly empty — say once "output starts on the human's word".
• Ideas look mature: suggest assembly in one sentence; never push twice.
• The human asks for output too early: comply, deliver the honestly thin result, and say which ideas are missing — never refuse.
• First assembly: state the sync rule in one sentence ("from here output updates only when you order a sync; edit output directly and I back-transcribe it into ideas").
• Every sync: give a one-line receipt of what was re-derived or back-transcribed.

Disciplines

• The never list: never pick sides, never invent judgments, never archive an idea on your own, never initiate first assembly on your own, never touch output outside the human's command.

• Markdown first: change the truth first, then rebuild every affected projection (indexes, canvas HTML) in the same turn; never edit a projection directly. Projections hold no facts and rebuild wholesale from markdown — committing one (the shared canvas) never promotes it to truth, and a committed canvas rides in the same change as the truth edit that made it stale.

• The ledger: logs.md is append-only and covers both ideas and output. Every change, one line per touched layer:

  - YYYY-MM-DD · card or doc · action · delta (old → new) · reason

  Record the delta itself — the minimal old → new — not just the action and reason. When the workspace sits outside git, the ledger is the only way back.

• Validation: two validators — scripts/check_workspace.py and scripts/check_doc_links.py — run automatically at bootstrap and on every canvas build: failure exits nonzero, prints the full problem list, and produces no HTML; fix the truth, then rebuild. When this file's contract changes, the validators change in the same commit.

Toolbox

All live in <skill-dir>/scripts/ and run standalone; command syntax sits at the usage sites (workflow steps 0 and 5).

• init_workspace.py — bootstrap: skeleton (idempotent, never clobbers) + registry write + runs both validators itself.
• discover_workspace.py — read-only discovery, prints which workspace resolves; ambiguity is reported, never resolved silently.
• build_canvas.py — the only canvas build entry; runs both validators as a gate, then emits the self-contained HTML.
• check_workspace.py — schema validation: required frontmatter, single tag, conflicts targets, forward-only acyclic references, no inbound board references.
• check_doc_links.py — link integrity: no dangling links inside the workspace.
• check_style_pack.py — style pack validation: dual palettes, no external reach, tokens aligned to the template.