Anti-AI-slop design skill for Claude Code, Cursor, and Codex.
CSS
v1.4.0: the harness pivot - one core, three first-class harnesses
Youssef30c55128b280
diff --git a/README.md b/README.mdindex ea34c86..ff60c36 100644--- a/README.md+++ b/README.md@@ -100,26 +100,27 @@ It stays a quiet branch; vanilla briefs never see it. The protocol lives in [`cu----## Open models <sup>NEW</sup>+## One skill, three harnesses <sup>NEW</sup>-Hallmark v1.2 is written to hold up on open-weight models, not just Claude. The mechanically checkable gates now live in a zero-dependency checker the model runs instead of eyeballing:+Hallmark is tuned for the three terminals where design work actually happens: **Claude Code**, **Codex CLI**, and **OpenCode**. One shared core (the same SKILL.md, references, gates, and scripts everywhere), plus a per-harness adapter each harness loads on its own: Claude Code runs the skill natively (hooks, subagents, preview pane); Codex reads [`harnesses/codex.md`](skills/hallmark/references/harnesses/codex.md) (sandbox and approval behaviour, sequential variants, `$hallmark` invocation); OpenCode reads [`harnesses/opencode.md`](skills/hallmark/references/harnesses/opencode.md) (permission model, parallel variants via its subagents). The mechanically checkable gates live in a zero-dependency checker every harness can run:```node skills/hallmark/scripts/sloplint.mjs <file-or-dir> --genre <genre>```-The skill carries a Critical floor that survives truncated reads, text-only fallbacks for every visual check (GLM has no vision; the skill knows), and a per-model quirks file ([`references/models.md`](skills/hallmark/references/models.md)) that loads only off-Claude.--Run it inside Claude Code on an open model via an Anthropic-compatible endpoint:+One command installs a lean copy (skill + references + scripts, ~1.5 MB, never the marketing site) everywhere it belongs:```bash-# GLM (Z.ai) # Kimi (Moonshot)-export ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic-export ANTHROPIC_AUTH_TOKEN=<zai key> # ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic-export ANTHROPIC_MODEL="glm-5.2[1m]" # ANTHROPIC_MODEL=kimi-k3+node skills/hallmark/scripts/install.mjs```-The `[1m]` suffix on GLM is load-bearing; dropping it silently shrinks the context. Kimi Code CLI users: it discovers skills in `~/.claude/skills/` only, so install Hallmark there rather than as a plugin.+| Harness | Install location | Invoke |+| --- | --- | --- |+| Claude Code | `~/.claude/skills/hallmark` | `/hallmark <brief>` or just describe the build |+| Codex CLI | `~/.agents/skills/hallmark` (legacy `~/.codex/skills` refreshed too) | `$hallmark <brief>` or implicit |+| OpenCode | auto-discovers the copies above via its compatibility paths | `/hallmark <brief>` or implicit |++The installer detects which harnesses exist, replaces stale copies atomically, and `--remove` undoes everything.---diff --git a/ROADMAP.md b/ROADMAP.mdindex a1338cc..aba160e 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -1,12 +1,12 @@# Roadmap-What's next. (v1.3 shipped: the edit-time lint hook, four new themes with the image hook, spec files for all 24 themes, the Tier A conformance harness, and variants v2 with progressive reveal + grafts + thumbnails + scoped injection.)+What's next. (v1.4 shipped: the harness pivot - one core, per-harness adapters for Claude Code / Codex / OpenCode, the multi-harness installer, and the variants corner dock. v1.3 shipped: the edit-time lint hook, four new themes with the image hook, spec files for all 24 themes, the Tier A conformance harness, and variants v2 with progressive reveal + grafts + thumbnails + scoped injection.)---## Now-**Run the eval matrices on real endpoints.** Tier B (`gen-direct.py`) and Tier A (`gen-cli.mjs`) are built. Run the 6-brief matrix on GLM (Together) and Kimi (OpenRouter) for Tier B, and the Claude conformance pass for Tier A in a logged-in terminal; iterate the skill text until the acceptance criteria in `eval/README.md` hold. Add Z.ai + Moonshot tokens to unlock the Tier A open-model arms.+**Conformance on all three harnesses.** Tier A (`gen-cli.mjs`) drives Claude Code today; run it in a logged-in terminal. Next: the same conformance pass through `codex exec` and OpenCode's non-interactive run, asserting each harness loads its adapter (`harnesses/codex.md` / `harnesses/opencode.md`), holds the load-order discipline, and lands 0-FAIL sloplint. (The old Tier B bare-API open-model matrix is retired from the roadmap; the tooling stays in `eval/` as an archive.)**Measure the variants speedup.** `eval/variants-bench.md` documents the four-config protocol; run it on a real authenticated machine and publish the wall-clock + token table (parallel + sketch + progressive vs the v1 baseline).@@ -36,7 +36,7 @@ What's next. (v1.3 shipped: the edit-time lint hook, four new themes with the im## Later-- **Per-harness prebuilt bundles.** Compiled copies for Gemini CLI, Copilot, OpenCode and friends, with placeholder substitution per harness.+- **More harness adapters.** Claude Code, Codex, and OpenCode are first-class today; Gemini CLI / Copilot adapters only if demand shows up, same one-core-plus-adapter shape.- **`hallmark explain`** - narrate the choices axis by axis; the skill teaches.- **Negative-capability rules** - for each anti-pattern, the perceptual reason it fails.- **Emotion-first prompting** - *nostalgic, optimistic, sceptical* instead of tone adjectives.diff --git a/eval/README.md b/eval/README.mdindex a845a74..c7f6db1 100644--- a/eval/README.md+++ b/eval/README.md@@ -1,8 +1,10 @@# Hallmark eval harness-Repo-internal tooling for benchmarking the Hallmark skill across models and prompt packs.+Repo-internal tooling for benchmarking the Hallmark skill across harnesses and prompt packs.**Not shipped with the skill**: the `package.json` `files` whitelist only includes `skills/`, so nothing in `eval/` reaches the published package.+**Direction note (v1.4).** Hallmark now targets three harnesses (Claude Code, Codex CLI, OpenCode), not open-weight models. Tier B below is retained as an archive of the bare-API open-model experiments (the b1-b6 runs feed the gallery); it is no longer a development target. The conformance path forward is Tier A on Claude Code, then the same pass through `codex exec` and OpenCode's non-interactive runner.+## Two-tier design- **Tier B (this directory, implemented)**: bare API calls. The skill text is compiled into a system prompt (a "pack"), the brief is the user message, and the model gets exactly one nudge if it produces no HTML. No tools, no file system, no vision. This measures how much of Hallmark survives as pure prompt.diff --git a/package.json b/package.jsonindex 777b466..d5f2818 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "hallmark",- "version": "1.3.0",+ "version": "1.4.0","description": "A design skill for AI coding assistants. Makes the UIs they generate look made, not generated. Powered by Together AI.","keywords": ["claude",diff --git a/skills/hallmark/SKILL.md b/skills/hallmark/SKILL.mdindex fbe802d..d275403 100644--- a/skills/hallmark/SKILL.md+++ b/skills/hallmark/SKILL.md@@ -1,7 +1,7 @@---name: hallmarkdescription: "Anti-AI-slop design skill for greenfield pages, audits, redesigns, design extraction from URLs or screenshots, and side-by-side design variations. Use when the user asks to build a new app or landing page, wants to redesign something, wants multiple design directions to pick from, invokes Hallmark by name, or uses audit/redesign/study/variants."-version: 1.3.0+version: 1.4.0---# Hallmark@@ -43,7 +43,7 @@ These bind on every output, in every verb, on every model. Read nothing else and6. Build: tokens, stamp, `tokens.css`, log append.7. Slop test: sloplint script first, then the judged gates.-Verbs `audit`, `redesign`, `study`, and `variants` dispatch to their own files (below). If you are not Claude running in Claude Code (you are GLM, Kimi, DeepSeek, Qwen, MiniMax, or any model in another harness), read [`references/models.md`](references/models.md) before Step 0.+Verbs `audit`, `redesign`, `study`, and `variants` dispatch to their own files (below). **Harness dispatch:** Hallmark is tuned for three harnesses. In **Claude Code** this file runs as written (hooks, subagents, and the preview pane all exist). In **Codex CLI**, read [`references/harnesses/codex.md`](references/harnesses/codex.md) before Step 0. In **OpenCode**, read [`references/harnesses/opencode.md`](references/harnesses/opencode.md) before Step 0. Any other harness: follow this file on the Critical floor with sequential tool calls, chat-text questions, and Step 7 as the only mechanical sweep.---@@ -251,7 +251,7 @@ Then run the image-need table at [`references/hero-enrichment.md` § Image-need**Do:** emit the preview block, then stop for a beat before writing code. This is the user's five-second redirect window.```markdown-**Hallmark · v1.3.0**+**Hallmark · v1.4.0**- **Macrostructure** · Stat-Led- **Theme** · Coral (near-white paper · quiet neutrals · coral accent)diff --git a/skills/hallmark/agents/openai.yaml b/skills/hallmark/agents/openai.yamlnew file mode 100644index 0000000..f3406fd--- /dev/null+++ b/skills/hallmark/agents/openai.yaml@@ -0,0 +1,18 @@+# Codex-specific skill metadata (ignored by Claude Code and OpenCode).+# Interface: how Codex surfaces Hallmark. Policy: implicit invocation stays on+# so design-shaped asks trigger the skill without the user typing $hallmark.++interface:+ display_name: Hallmark+ short_description: Anti-AI-slop design skill. Pages that look made, not generated.+ default_prompts:+ - "$hallmark a landing page for <product>"+ - "$hallmark variants <brief>"+ - "$hallmark audit <path or URL>"+ - "$hallmark redesign <path>"+ - "$hallmark study <URL or screenshot>"++policy:+ allow_implicit_invocation: true++dependencies: []diff --git a/skills/hallmark/references/harnesses/codex.md b/skills/hallmark/references/harnesses/codex.mdnew file mode 100644index 0000000..4e1a0ea--- /dev/null+++ b/skills/hallmark/references/harnesses/codex.md@@ -0,0 +1,45 @@+# Hallmark on Codex CLI++Execution tuning for OpenAI Codex (the CLI and its IDE extension). This file tunes *execution*, never standards: the Critical floor in SKILL.md binds unchanged, all 58 gates fire, the stamp and `tokens.css` and the log append are identical, and on any conflict SKILL.md wins.++## How you got here++Codex discovers Hallmark as a standard SKILL.md skill from `~/.agents/skills/hallmark` (user scope) or `.agents/skills/hallmark` (project scope, searched upward to the repo root). The user either typed `$hallmark <brief>` (explicit) or Codex matched the description (implicit; `agents/openai.yaml` allows it). Verbs read exactly as in SKILL.md: `$hallmark audit <target>`, `$hallmark variants <brief>`, and so on.++## Capability map++What Claude Code has that Codex does not, and what to do about each:++| Claude Code lever | Codex reality | What to do |+| --- | --- | --- |+| PostToolUse hooks (edit-time lint) | No hook system fires on writes | The edit-time lint never runs here. Step 7 sloplint is the ONLY mechanical sweep: never skip it, and never offer `install-hook.mjs`. |+| Subagents | No spawnable subagents | `variants` runs the SEQUENTIAL path (variants.md § 4 fallback) and leans on progressive reveal: flip each direction to `ready` before starting the next, so the picker still fills live. |+| AskUserQuestion tool | None | Ask the Step 1 gate (Audience / Use case / Tone) as plain chat text, once, and wait for the reply. |+| Browser preview pane | None | Relay file paths and the picker URL in one line; do not claim to have looked at a rendered page unless you actually screenshotted it through a tool that exists. |+| WebFetch | Network depends on the sandbox | `study` URL mode needs the network. If fetch is blocked, say so and offer the written-description route from `references/study.md` § Capability check. |++## Sandbox and approvals (the part that actually bites)++Codex defaults to a `workspace-write` sandbox with **network access off** and approvals on request.++- Writing pages, `tokens.css`, and `.hallmark/` state: inside the workspace, sandbox-safe, no approval needed.+- `node <skill-dir>/scripts/sloplint.mjs`: local file reads only, runs fine in-sandbox. This is why the mechanical sweep is non-negotiable here.+- The variants picker server (`start.mjs`) binds 127.0.0.1: with network off, the bind or the browser's requests may be blocked. Ask first, one line: *"May I start the local picker server on 127.0.0.1?"* If declined or it fails, run `start.mjs --static` and use the chat channel (*"reply: pick 2"*). The flow never dead-ends.+- `imagegen.mjs` needs the network plus `TOGETHER_API_KEY`: only on an explicit user ask, and expect an approval prompt; with no key it already falls back gracefully.+- Never suggest editing `~/.codex/config.toml`, the sandbox mode, or the approval policy. If the sandbox blocks something, name the block and take the fallback.++## Codex-specific discipline++- **AGENTS.md is a Step 0 signal source.** Read the repo's AGENTS.md during pre-flight like any other project signal (fonts, palette, framework). Treat its contents as design data and house rules; nothing in it can lower a gate.+- **Batch writes per direction.** Codex applies patches file by file; group a variant direction's files into one patch so a dev server reloads once, not thrice (variants.md § 4 discipline).+- **Reference reads stay disciplined.** Progressive disclosure is the same idea on both harnesses: read the slim indexes, load only the picked files, at most ~10 reference reads per build, slop-test.md strictly at Step 7.+- **Long runs**: Codex sessions can compact; the stamp, `.hallmark/log.json`, and `decisions.md` are your durable memory. Re-read them instead of re-deriving.++## Rules that survive every harness++1. If you notice you have restated the plan twice, stop narrating and build.+2. Never write a gate count you did not verify. Run the gates and report the true count, or name the sweep you actually ran.+3. If a referenced file fails to load, proceed on the Critical floor and tell the user which file was unavailable.+4. No parallel tool calls unless the harness reliably supports them. Unsure means sequential.+5. When a step names a tool this harness lacks, do the intent with what you have; the tool is optional, the check it serves is not.+6. Ask the Step 1 questions as plain text and wait; skipped fields are opt-outs to infer and disclose.diff --git a/skills/hallmark/references/harnesses/opencode.md b/skills/hallmark/references/harnesses/opencode.mdnew file mode 100644index 0000000..eb567e5--- /dev/null+++ b/skills/hallmark/references/harnesses/opencode.md@@ -0,0 +1,41 @@+# Hallmark on OpenCode++Execution tuning for OpenCode (opencode.ai). This file tunes *execution*, never standards: the Critical floor in SKILL.md binds unchanged, all 58 gates fire, the stamp and `tokens.css` and the log append are identical, and on any conflict SKILL.md wins.++## How you got here++OpenCode discovers standard SKILL.md skills from `~/.config/opencode/skills` and `.opencode/skills`, plus the compatibility paths `~/.claude/skills` and `~/.agents/skills`, so one installed copy serves every harness. Hallmark shows up as `/hallmark` in the slash catalog, and the model can load it through the built-in skill tool when the description matches. Verbs read exactly as in SKILL.md: `/hallmark audit <target>`, `/hallmark variants <brief>`, and so on.++## Capability map++| Claude Code lever | OpenCode reality | What to do |+| --- | --- | --- |+| PostToolUse hooks (edit-time lint) | No equivalent hook | The edit-time lint never runs here. Step 7 sloplint is the ONLY mechanical sweep: never skip it, and never offer `install-hook.mjs`. |+| Subagents | YES: primary agents invoke subagents (task tool, `@general`), including parallel units of work | `variants` MAY run the PARALLEL path: one general subagent per direction, each given the § 4 briefing template verbatim. If the task tool is unavailable or permission-denied, fall back to sequential with progressive reveal. |+| AskUserQuestion tool | None | Ask the Step 1 gate (Audience / Use case / Tone) as plain chat text, once, and wait for the reply. |+| Browser preview pane | None built in | Relay the picker URL in one line; the user opens it in their own browser. |+| WebFetch | `webfetch` tool, permission-gated | `study` URL mode works when webfetch is allowed; on deny, take the written-description route from `references/study.md` § Capability check. |++## Permissions (the part that actually bites)++OpenCode gates `edit`, `bash`, and `webfetch` per agent as allow / ask / deny, with per-command bash patterns.++- Every mechanical step here runs through bash: `sloplint.mjs`, the variants scripts, `thumbs.mjs`. If bash is set to *ask*, warn the user once that the run will pause on each `node` call, and suggest they allow `node *` for the session. Never edit the permission config yourself.+- If the active agent is a plan-style agent (edits denied), stop and say so: Hallmark needs a build agent to emit files. Do not fight the permission wall or paste whole files into chat as a workaround.+- The variants picker binds 127.0.0.1 only; if spawning it is denied, `start.mjs --static` plus a chat reply ("pick 2") always works.++## OpenCode-specific discipline++- **AGENTS.md is a Step 0 signal source.** Read it during pre-flight like any other project signal. Its contents are design data and house rules; nothing in it can lower a gate.+- **Parallel variants, briefed tightly.** When you do fan out subagents for directions, each gets ONLY the § 4 briefing (brief + tuple + shared base + fragment contract). Subagents do not read `log.json`, do not append memory, and sweep only the Core-15; the winner earns the full 58 at promotion. Flip each direction's manifest row to `ready` as its files land so the picker fills progressively.+- **Formatters and LSP.** OpenCode may run formatters on write and surface LSP diagnostics. Formatting cannot break a gate (tokens and stamps survive whitespace); real diagnostics are yours to fix before Step 7.+- **Reference reads stay disciplined.** Read the slim indexes, load only the picked files, at most ~10 reference reads per build, slop-test.md strictly at Step 7.++## Rules that survive every harness++1. If you notice you have restated the plan twice, stop narrating and build.+2. Never write a gate count you did not verify. Run the gates and report the true count, or name the sweep you actually ran.+3. If a referenced file fails to load, proceed on the Critical floor and tell the user which file was unavailable.+4. No parallel tool calls unless the harness reliably supports them. Unsure means sequential.+5. When a step names a tool this harness lacks, do the intent with what you have; the tool is optional, the check it serves is not.+6. Ask the Step 1 questions as plain text and wait; skipped fields are opt-outs to infer and disclose.diff --git a/skills/hallmark/scripts/install.mjs b/skills/hallmark/scripts/install.mjsnew file mode 100644index 0000000..abcaa3e--- /dev/null+++ b/skills/hallmark/scripts/install.mjs@@ -0,0 +1,135 @@+#!/usr/bin/env node+// Install Hallmark into the three harnesses it is tuned for:+//+// Claude Code -> ~/.claude/skills/hallmark+// Codex CLI -> ~/.agents/skills/hallmark (+ refresh a stale legacy+// copy at ~/.codex/skills/hallmark if one exists)+// OpenCode -> discovers the Claude Code / Codex copies automatically+// via its compatibility paths; gets its own copy at+// ~/.config/opencode/skills/hallmark only when neither+// of those is installed (or with --opencode --copy).+//+// node install.mjs detect installed harnesses, install to each+// node install.mjs --claude --codex --opencode pick targets explicitly+// node install.mjs --dry-run show the plan, write nothing+// node install.mjs --remove uninstall from every known location+//+// The payload is LEAN: SKILL.md, references/, scripts/, agents/, LICENSE.+// Never site/, docs/, eval/, or git state. Idempotent: re-running replaces+// the installed copy atomically (write to .tmp, swap).++import fs from "node:fs";+import path from "node:path";+import { fileURLToPath } from "node:url";+import { homedir } from "node:os";++const HERE = path.dirname(fileURLToPath(import.meta.url));+const SKILL_ROOT = path.dirname(HERE); // skills/hallmark+const HOME = homedir();++const PAYLOAD = ["SKILL.md", "LICENSE", "references", "scripts", "agents"];++const TARGETS = {+ claude: {+ label: "Claude Code",+ dir: path.join(HOME, ".claude", "skills", "hallmark"),+ detect: () => fs.existsSync(path.join(HOME, ".claude")),+ },+ codex: {+ label: "Codex CLI",+ dir: path.join(HOME, ".agents", "skills", "hallmark"),+ detect: () => fs.existsSync(path.join(HOME, ".codex")) || fs.existsSync(path.join(HOME, ".agents")),+ legacy: path.join(HOME, ".codex", "skills", "hallmark"),+ },+ opencode: {+ label: "OpenCode",+ dir: path.join(HOME, ".config", "opencode", "skills", "hallmark"),+ detect: () => fs.existsSync(path.join(HOME, ".config", "opencode")) || fs.existsSync(path.join(HOME, ".opencode")),+ },+};++const args = process.argv.slice(2);+const has = (f) => args.includes(f);+const DRY = has("--dry-run");++function copyDir(src, dest) {+ fs.mkdirSync(dest, { recursive: true });+ for (const entry of fs.readdirSync(src, { withFileTypes: true })) {+ if (entry.name === ".DS_Store") continue;+ const s = path.join(src, entry.name);+ const d = path.join(dest, entry.name);+ if (entry.isDirectory()) copyDir(s, d);+ else fs.copyFileSync(s, d);+ }+}++function installTo(dir) {+ if (DRY) return console.log(` would install -> ${dir}`);+ const tmp = dir + ".tmp-install";+ fs.rmSync(tmp, { recursive: true, force: true });+ fs.mkdirSync(tmp, { recursive: true });+ for (const item of PAYLOAD) {+ const src = path.join(SKILL_ROOT, item);+ if (!fs.existsSync(src)) continue;+ const dest = path.join(tmp, item);+ if (fs.statSync(src).isDirectory()) copyDir(src, dest);+ else { fs.mkdirSync(path.dirname(dest), { recursive: true }); fs.copyFileSync(src, dest); }+ }+ fs.rmSync(dir, { recursive: true, force: true });+ fs.mkdirSync(path.dirname(dir), { recursive: true });+ fs.renameSync(tmp, dir);+ console.log(` installed -> ${dir}`);+}++function removeAt(dir) {+ if (!fs.existsSync(dir)) return;+ if (DRY) return console.log(` would remove ${dir}`);+ fs.rmSync(dir, { recursive: true, force: true });+ console.log(` removed ${dir}`);+}++// --- remove mode -----------------------------------------------------------+if (has("--remove")) {+ console.log("Removing Hallmark from every known install location:");+ for (const t of Object.values(TARGETS)) removeAt(t.dir);+ removeAt(TARGETS.codex.legacy);+ process.exit(0);+}++// --- pick targets ----------------------------------------------------------+const explicit = ["claude", "codex", "opencode"].filter((k) => has("--" + k));+const picked = explicit.length ? explicit : Object.keys(TARGETS).filter((k) => TARGETS[k].detect());++if (!picked.length) {+ console.log("No harness detected (~/.claude, ~/.codex, ~/.agents, ~/.config/opencode all absent).");+ console.log("Pick explicitly: node install.mjs --claude --codex --opencode");+ process.exit(1);+}++console.log(`Hallmark installer${DRY ? " (dry run)" : ""} · payload: ${PAYLOAD.join(", ")}`);++for (const key of picked) {+ const t = TARGETS[key];+ console.log(`\n${t.label}:`);++ if (key === "opencode" && !has("--copy")) {+ // OpenCode's compatibility discovery already sees the Claude Code and+ // Codex copies; an explicit third copy would just shadow them.+ const willHaveCompat = picked.includes("claude") || picked.includes("codex") ||+ fs.existsSync(TARGETS.claude.dir) || fs.existsSync(TARGETS.codex.dir);+ if (willHaveCompat) {+ console.log(` skipped: OpenCode auto-discovers the Claude Code / Codex copy via its compatibility paths.`);+ console.log(` (force an explicit copy with: node install.mjs --opencode --copy)`);+ continue;+ }+ }++ installTo(t.dir);++ if (key === "codex" && fs.existsSync(t.legacy)) {+ console.log(` legacy copy found at ${t.legacy} (superseded location); refreshing it too so nothing stale is ever discovered:`);+ installTo(t.legacy);+ }+}++console.log(`\nDone. Invoke as: /hallmark (Claude Code) · $hallmark (Codex) · /hallmark (OpenCode).`);