ForgetMe Design Harness

From approved intent to evidence-backed web UI.
A guided workflow for Codex and Claude Code that interviews first, uses a single design authority for production, reviews independently, and verifies what can be measured.

Русский · English · 简体中文

interview → approved context → design & build → feedback → independent review → QA evidence

Overview · Quick start · Workflow · Roles · Install · Check · QA · Claude plugin · Optional tools · Docs

Overview

Design Harness is not another “make it pretty” prompt, and it is not a pile of simultaneously active design skills. It keeps responsibility explicit:

Impeccable is the only broad design and production authority.
Seven Jakub Krehel skills perform an independent, read-only review after the build.
Detector and browser QA establish facts that should not depend on model taste.
Optional carriers are enabled only for one approved, narrow task.

Documentation and commands in this repository describe release v0.2.1.

Most importantly, intent is never invented silently. The workflow asks adaptive questions, accepts positive and negative references as screenshots or links, and can use a plain-language description when references do not exist. If the user delegates a choice, the workflow proposes a direction and still waits for approval.

Quick start

Requires Node.js 22.20.0 or newer. The package is currently distributed through the GitHub release; it has not been published to the npm registry.

The exact v0.2.1 asset passed fresh Codex installation on Ubuntu and macOS with Node.js 22.20.0; see public run 31169086066.

npx --yes --package=https://github.com/ForgetMeAI/design-harness/releases/download/v0.2.1/forgetme-design-harness-0.2.1.tgz forgetme-design-harness install

Verify the core installation:

npx --yes --package=https://github.com/ForgetMeAI/design-harness/releases/download/v0.2.1/forgetme-design-harness-0.2.1.tgz forgetme-design-harness check --installation-only

Expected result:

installation: ready
QA tooling/config: deliberately skipped by --installation-only

Then open the target project in Codex and say:

Use $design-harness to build my portfolio website.

The default command installs project-local entry skills for both Codex and Claude Code, then runs the pinned upstream installers for Impeccable and all seven Jakub review skills.

Note

In Codex, open /hooks after installation and approve Impeccable's project hook.

Workflow

flowchart LR
    A["Adaptive interview"] --> B{"User approval"}
    B --> C["Intent files"]
    C --> D["Design and build<br/>Impeccable"]
    D --> E["Internal review"]
    E --> F["Optional feedback<br/>Agentation"]
    F --> G["Read-only review<br/>7 Jakub skills"]
    G --> H["Adjudicated fixes<br/>through Impeccable"]
    H --> I["QA evidence<br/>detector + browser"]

One invocation guides the project through:

Project and capability preflight.
A short, adaptive interview covering audience, goals, content, surfaces, desired and undesired qualities, references, constraints, motion, states, stack, AI-specific behavior, WebGL tolerance, and license boundaries.
One concise understanding card and explicit user approval.
User-owned context files: PRODUCT.md, REFERENCES.md, DESIGN.md, ACCEPTANCE.md, and at least one .impeccable/surfaces/<slug>.md brief.
Design, implementation, and internal review through Impeccable.
An optional, development-only human-annotation round.
A fresh read-only Jakub review, finding adjudication, and approved fixes.
Detector, Playwright, axe, Lighthouse, and motion evidence where configured.
An honest verdict that includes screenshots, unresolved findings, and anything that could not be reviewed.

No intent file is marked approved before its content is approved. Later changes to PRODUCT.md or DESIGN.md require a visible proposed diff and another explicit approval. Every external component, effect, or recipe must be recorded in REFERENCES.md with its exact source, selected item, version or commit when available, access date, purpose, license result, adaptations, and fallback.

Role separation

Participant	Authority	Must not do
User	Product intent, references, constraints, acceptance, and approval	Be bypassed when intent or protected files change
Design Harness	Orchestrate phases, preserve state, route work, and report evidence	Invent approval or act as a second art director
Impeccable	Only broad design and production authority for the pass	Re-run discovery or silently reinterpret approved intent
Jakub review set	Independent post-build findings through `better-interface` plus six domain checks	Edit code, redesign silently, or become a competing production authority
Detector and browser QA	Reproducible checks and visual evidence	Convert missing coverage into a green result
Optional tools	One explicitly approved, narrow job	Install by default or broaden their own scope

The seven read-only review skills are better-interface, better-accessibility, better-colors, better-layout, better-typography, better-ui, and better-writing.

See the complete phase and authority contract in docs/WORKFLOW.md.

Installation

Install the orchestrator only

npx --yes --package=https://github.com/ForgetMeAI/design-harness/releases/download/v0.2.1/forgetme-design-harness-0.2.1.tgz forgetme-design-harness install --skip-upstreams

Useful flags

Flag	Meaning
`--host codex\|claude\|both`	Installation host; default: `both`
`--scope project\|user`	Installation scope; default: `project`
`--target <path>`	Root of a project-scoped installation
`--dry-run`	Show planned changes without writing
`--force`	Replace only an existing `design-harness` installation
`--skip-upstreams`	Do not run the Impeccable and Jakub installers
`--installation-only`	`check` only: validate core installation without the project QA gate
`--json`	Return machine-readable output

What upstream installation verifies

The installer pins:

Impeccable CLI 3.5.0;
the official Impeccable skill-v4.0.4/universal.zip release asset, verified as a whole archive against its recorded SHA-256 before the CLI can read it;
the skills CLI to 1.5.21;
the Jakub source archive to commit a67333399dabbc71d7778962cb9c4fb9b86a00d0.

A download failure or archive digest mismatch stops before Impeccable runs. Temporary-download cleanup is always attempted; a cleanup failure is reported explicitly instead of hiding the original error. A successful external process is still not enough. Harness verifies pinned SHA-256 core files for all eight upstream skills on every selected host. The seven small Jakub skills use exact-tree verification, so an unexpected extra file is also drift. The larger Impeccable installation uses explicitly reported pinned-sentinels: host-specific instructions, linked guidance, detector files, hook entry points, and their local import closure. It does not claim to hash the entire Impeccable tree.

Before each external step, Harness snapshots the affected skill directories and known hook configurations. A non-zero exit or integrity mismatch rolls back that limited set. This rollback is not a sandbox: an explicitly authorized npm or GitHub installer can theoretically affect other files or external state. Harness restores selected upstream skill directories, new entries in their skill roots, and known Impeccable hook sidecars. Any incomplete rollback is reported as a separate error and its backup is preserved.

Do not recover by running a failed upstream command on its own: rerun the full Harness installation with --force so integrity verification is repeated.

Third-party source code is not bundled into Design Harness. Normal installation fetches only the pinned Impeccable and Jakub upstreams; the optional registry is routing metadata and installs nothing.

Check and status semantics

npx --yes --package=https://github.com/ForgetMeAI/design-harness/releases/download/v0.2.1/forgetme-design-harness-0.2.1.tgz forgetme-design-harness check

Important

check validates installation integrity and the presence of QA tooling and meaningful configuration. It does not execute QA, inspect the finished UI, or replace fresh detector, Playwright, axe, or Lighthouse reports.

The check command itself does not use the network. The surrounding npx command may download the release when it is not cached; an installed CLI can instead run forgetme-design-harness check directly.

The report separates installation: ready from QA tooling/config: ready.
Missing Impeccable or any of the seven Jakub skills fails installation status.
QA readiness requires local node_modules, Playwright/axe/Lighthouse, and meaningful Playwright and Lighthouse configuration. A package entry or an unrelated test config is not enough.
check --installation-only gates core installation, explicitly marks QA as skipped, and does not present it as passed.
A user-scoped run checks installation only; run project-scoped QA readiness from the project root.
On a fresh target without upstream skills or QA setup, an installation made with --skip-upstreams intentionally returns a non-zero full-check result and lists the missing core skills and QA capabilities. Existing valid upstream skills are not removed.

Codex discovers project skills under .agents/skills, walking from the current directory to the Git root, as described in the official Codex skills guide. If $design-harness or /skills does not show the skill, open a new task from the target project root. If needed, restart Codex and run check again.

QA without invented confidence

The workflow can scaffold project-local checks for:

Playwright screenshots at mobile, tablet, and desktop widths;
axe accessibility scans;
reduced-motion behavior;
Lighthouse CI without public report uploads;
the Impeccable detector;
deterministic startup and scroll-motion evidence.

Loading, empty, error, and long-copy states depend on application-specific routes or fixtures. When a state cannot be reproduced, the verdict is Not reviewed, not green. Screenshot mismatches are never accepted automatically, and a successful capture is not a baseline pixel-diff pass unless the project configures one. Agentation must be absent from the production bundle, and motion must not be the sole carrier of meaning; reduced-motion and non-WebGL fallbacks remain part of acceptance.

Claude Code plugin

The plugin contains the orchestrator, not third-party Impeccable or Jakub sources. Bootstrap a fully verifiable project-local installation first; this also creates the standalone /design-harness command:

npx --yes --package=https://github.com/ForgetMeAI/design-harness/releases/download/v0.2.1/forgetme-design-harness-0.2.1.tgz forgetme-design-harness install --host claude --target .
npx --yes --package=https://github.com/ForgetMeAI/design-harness/releases/download/v0.2.1/forgetme-design-harness-0.2.1.tgz forgetme-design-harness check --installation-only --host claude --target .

Then install the marketplace adapter when a namespaced command is useful:

/plugin marketplace add ForgetMeAI/design-harness
/plugin install design-harness@forgetme-design-harness
/reload-plugins
/design-harness:design-harness

Standalone invocation:

/design-harness Build my portfolio website.

Local plugin development:

claude plugin validate adapters/claude-code --strict
claude --plugin-dir adapters/claude-code

Optional tools

View the opt-in registry and its guardrails

None of these tools is installed or activated by default. Before activation, Harness records the exact source and version, intended purpose, current license or terms result, required fallback, and explicit user approval.

Route	Allowed narrow use	Guardrail
Agentation	Development-only human annotations after the first build	Local/manual by default; MCP, webhooks, persistence, or autonomous resolution require separate opt-in; never ship it in production
transitions.dev	Review or normalize ordinary product transitions	Start with read-only `review`, `refine`, or `polish`; code-changing `apply` requires approval
Border Beam	One semantic `active`, `live`, or `processing` state, or one priority CTA	Never use as general decoration
Thinking Orbs	A real AI state with visible text and accessibility semantics	Require a static reduced-motion fallback
AICSS	An approved agent or chat surface	Verify access and the exact component before use
Beautiful UI	Pattern and reference catalog	Do not copy code without a confirmed license
Originkit	One approved effect or primitive	Verify browser/performance budget, reduced motion, license, and fallback
Canvas UI	One approved live-HTML WebGL effect	Verify browser/performance budget and reduced motion; require a functional non-WebGL fallback
Metal FX	One approved signature WebGL effect	Verify browser/performance budget and reduced motion; require a functional non-WebGL fallback

Existing narrow routes remain narrow: shadcn only for a suitable React/product UI, Storybook only when the project truly needs a component system, and image generation only when approved direction needs original assets. GSAP is reserved for genuinely complex motion and retains its own non-OSI open-source license.

Development

Validate a checkout without modifying an open project:

npm ci
npm run validate
npm run pack:check

Common contributor loop:

npm run sync:claude
npm test
npm run validate
npm pack --dry-run

The canonical skill lives in skills/design-harness/. The generated Claude Code adapter lives in adapters/claude-code/ because Claude supports an additional manual-invocation field. Do not edit the generated copy directly.

Privacy and security

Design Harness requires no API keys and stores no chat history. Machine state contains only the phase, paths, and minimal checkpoint data. Never place credentials in PRODUCT.md, DESIGN.md, reference files, or reports.

Agentation annotations may contain interface text, selectors, and page context. Harness keeps them local to development by default. MCP or persistent storage is a separate opt-in and must not be enabled on pages containing credentials or sensitive user data.

Report vulnerabilities through SECURITY.md, not a public issue.

Documentation

Resource	Purpose
`docs/WORKFLOW.md`	Complete state, authority, routing, and verification contract
`CHANGELOG.md`	Release history
`release/RELEASE_NOTES_v0.2.1.md`	Checksums, changes, and public smoke evidence
`release/release-manifest.json`	Exact release version, asset, and SHA-256 values
`release/VERIFICATION_v0.2.1.md`	Two local cold installs and the public Ubuntu/macOS matrix
`THIRD_PARTY.md`	Pinned upstreams, optional tools, and license notes
`CONTRIBUTING.md`	Contribution workflow
`SECURITY.md`	Supported version and private reporting process

Design Harness code is licensed under MIT. Impeccable, Jakub skills, Playwright, axe, Lighthouse, and every optional tool retain their own terms; see THIRD_PARTY.md before redistribution or activation.

Built by ForgetMe AI · Release v0.2.1 · Report an issue

FilesExpand file tree

README.en.md

Latest commit

History