borghei/Claude-Skills / engineering/marketing-site-builder
marketing-site-builder
VerifiedBuild company, product and landing sites that do not look generic: one system, plain copy, real imagery, restrained motion, a static finish gate. Use when building, restyling or reviewing a marketing site, or a page reads as templated.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.5 KB |
| assets/copy_tells.json | config | 6.9 KB |
| assets/flawed_page.html | other | 6.8 KB |
| assets/flawed_utility_page.html | other | 1.7 KB |
| assets/malformed_page.html | other | 86 B |
| assets/sample_budget_strict.json | config | 934 B |
| assets/site-plan-template.md | markdown | 2.7 KB |
| assets/site_budget.json | config | 1002 B |
| assets/sound_page.html | other | 7.5 KB |
| assets/sound_page_de.css | other | 1.4 KB |
| assets/sound_page_de.html | other | 2.8 KB |
| references/copy-voice-and-tells.md | markdown | 14.4 KB |
| references/finish-gate.md | markdown | 13.1 KB |
| references/imagery-motion-effects.md | markdown | 8.6 KB |
| references/one-system-and-rhythm.md | markdown | 9.2 KB |
| references/sections-cards-forms.md | markdown | 8.9 KB |
| scripts/access_links_check.py | script | 14.3 KB |
| scripts/consistency_check.py | script | 15.2 KB |
| scripts/copy_devices.py | script | 13.2 KB |
| scripts/copy_lint.py | script | 14.4 KB |
| scripts/finish_gate.py | script | 12.1 KB |
| scripts/page_gate.py | script | 17.8 KB |
| scripts/style_rules.py | script | 10.9 KB |
scripts/finish_gate.py
View on GitHub#!/usr/bin/env python3
"""Run every static check on a page, apply written waivers, count fix rounds,
and end on one verdict line.
The six checkers in this folder each report on their own. This gate runs them
all in-process (copy_lint, copy_devices, consistency_check, page_gate,
access_links_check, style_rules), applies a waiver file in which each waiver
names one finding and gives its reason, and, with --state, counts a round each
time the page or the waivers change. Its last line is one of:
GATE: PASS
GATE: FAIL <n> (round <k> of <max>)
GATE: OPEN <n> (rounds used up) stop fixing; report what is open
GATE: DONE (<the user's words>) the user ended the build
Usage:
python3 finish_gate.py index.html --kind place
python3 finish_gate.py index.html --waivers site-waivers.json --state .site-gate.json
python3 finish_gate.py index.html --state .site-gate.json --done "client said ship it as it is"
Waiver file: a JSON list of {"check": "<finding id>", "target": "<text from the finding>",
"reason": "<12+ characters>"}. A waiver that matches more than one finding is ignored.
More than five waivers is itself a FAIL. checker-gaming cannot be waived.
Exit codes: 0 PASS or DONE, 1 FAIL or OPEN, 2 bad input.
"""
from __future__ import annotations
import argparse
import datetime as dt
import hashlib
import importlib.util
import json
import re
import sys
from pathlib import Path
from typing import Dict, List, Optional
HERE = Path(__file__).resolve().parent
UNWAIVABLE = {"checker-gaming", "too-many-waivers"}
MAX_WAIVERS = 5
def _sibling(name: str):
"""Load a sibling script as a module without a package import."""
spec = importlib.util.spec_from_file_location(name, HERE / f"{name}.py")
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
return mod
CL, CD, CC, PG, AL, SR = (_sibling(n) for n in ("copy_lint", "copy_devices", "consistency_check",
"page_gate", "access_links_check", "style_rules"))
ERRORS = (CL.InputError, CC.InputError, AL.InputError, ValueError, OSError, KeyError, TypeError, re.error)
def norm(script: str, f: Dict) -> Dict:
"""One finding shape for every checker."""
where = f.get("where") or (f"L{f['line']}" if f.get("line") else "page")
text = f.get("match") or ""
return {"script": script, "severity": f["severity"], "id": f["id"], "where": where,
"text": text, "message": f.get("message", ""), "key": f"{script} {f['id']} {where} {text} {f.get('message', '')}"}
def run_all(page: Path, a: argparse.Namespace, budget: Dict) -> tuple:
"""Run each checker; return its normalised findings and the CSS text read (for the round signature)."""
segs, lex, is_html = CL.load(page, Path(a.lexicon))
res = {"copy_lint": [norm("copy_lint", f) for f in CL.lint(segs, lex, is_html, a.allow, a.year)],
"copy_devices": [norm("copy_devices", f) for f in CD.analyse(page, Path(a.lexicon))["findings"]]}
if not is_html:
return res, []
try:
sources, buttons = CC.gather(page, a.css)
except CC.InputError as exc: # a page with no readable CSS still gets every other check
if "no CSS found" not in str(exc):
raise
sources = None
res["page_gate"] = [norm("page_gate", f) for f in PG.gate(page, a.kind, budget["page"])["findings"]]
res["access_links_check"] = [norm("access_links_check", f) for f in AL.check(page)["findings"]]
if sources is None:
res["consistency_check"] = [norm("consistency_check", {"severity": "FAIL", "id": "no-css", "where": "css", "message":
"no stylesheet read (remote or not built yet): pass the built CSS with --css"})]
return res, []
cons = CC.analyse(sources, buttons, budget["system"])
res["consistency_check"] = [norm("consistency_check", {"severity": "FAIL", "id": cat, "where": "css",
"message": f"{r['distinct']} distinct, budget {r['budget']}"})
for cat, r in cons["categories"].items() if r["over"]] + \
[norm("consistency_check", {"severity": "WARN", "id": w["id"], "where": w["where"],
"match": w["value"], "message": w["message"]}) for w in cons["warnings"]]
res["style_rules"] = [norm("style_rules", f) for f in SR.check(page, a.css)["findings"]]
return res, [src for src, _, _ in sources]
def load_waivers(path: Optional[Path]) -> tuple:
"""Return (valid waivers, notes about ignored ones); raise ValueError on a malformed file."""
if path is None or not path.is_file():
return [], []
try:
data = json.loads(path.read_text(encoding="utf-8"))
except json.JSONDecodeError as exc:
raise ValueError(f"waiver file is not valid JSON: {path}: {exc}") from exc
if not isinstance(data, list):
raise ValueError("waiver file must be a JSON list of {check, target, reason}")
valid, notes = [], []
for i, w in enumerate(data):
if not isinstance(w, dict) or not all(isinstance(w.get(k), str) for k in ("check", "target", "reason")):
notes.append(f"waiver {i + 1} ignored: needs check, target and reason as text")
elif len(w["reason"].strip()) < 12:
notes.append(f"waiver {i + 1} ({w['check']}) ignored: the reason is under 12 characters")
elif len(w["target"].strip()) < 3:
notes.append(f"waiver {i + 1} ({w['check']}) ignored: the target is under 3 characters")
else:
valid.append(w)
return valid, notes
def apply_waivers(findings: List[Dict], waivers: List[Dict], notes: List[str]) -> None:
"""Mark the one FAIL each waiver names as WAIVED; note waivers that match none or several."""
for w in waivers:
hits = [f for f in findings if f["severity"] == "FAIL" and f["id"] == w["check"] and w["target"].lower() in f["key"].lower()]
if len(hits) == 1 and hits[0]["id"] not in UNWAIVABLE:
hits[0]["severity"], hits[0]["reason"] = "WAIVED", w["reason"]
elif len(hits) > 1:
notes.append(f"waiver for {w['check']} '{w['target']}' matches {len(hits)} findings: name one")
elif hits:
notes.append(f"{w['check']} cannot be waived")
else:
notes.append(f"waiver for {w['check']} '{w['target']}' matches no FAIL")
def signature(files: List[Path], css: List[str]) -> str:
"""Hash of the page, waivers, budget, lexicon and every stylesheet read, so an unchanged rerun is not a round."""
h = hashlib.sha256()
for p in files:
h.update(p.read_bytes() if p.is_file() else b"-")
for text in css:
h.update(text.encode("utf-8", "replace"))
return h.hexdigest()
def main() -> None:
"""CLI entry point."""
ap = argparse.ArgumentParser(description="Run every static check, apply waivers, count rounds, print one GATE line.")
ap.add_argument("path", help="HTML page (a .md/.txt draft runs the two copy checks only)")
ap.add_argument("--kind", choices=PG.KINDS, help="business kind (default: <html data-kind>)")
ap.add_argument("--css", action="append", default=[], help="extra built stylesheet (repeatable)")
ap.add_argument("--budget", default=str(PG.DEFAULT_BUDGET), help="budget JSON (default: assets/site_budget.json)")
ap.add_argument("--lexicon", default=str(CL.DEFAULT_LEXICON), help="copy lexicon JSON (default: assets/copy_tells.json)")
ap.add_argument("--allow", action="append", default=[], help="a word literal for the trade (repeatable)")
ap.add_argument("--year", type=int, default=dt.date.today().year, help="current year for the copyright check")
ap.add_argument("--waivers", help="waiver JSON (default: site-waivers.json beside the page, if present)")
ap.add_argument("--state", help="round counter JSON; without it rounds are not tracked")
ap.add_argument("--max-rounds", type=int, default=3, help="fix rounds before the gate reports OPEN (default 3)")
ap.add_argument("--done", help="the user's own words ending the build (12+ characters); needs --state")
ap.add_argument("--format", choices=["text", "json"], default="text", help="output format")
args = ap.parse_args()
page = Path(args.path)
wpath = Path(args.waivers) if args.waivers else page.parent / "site-waivers.json"
try:
if args.done is not None and (len(args.done.strip()) < 12 or not args.state):
raise ValueError("--done takes the user's words (12+ characters) and needs --state")
if args.max_rounds < 1:
raise ValueError("--max-rounds must be 1 or more")
budget = CC.validate_budget(json.loads(CC.read(Path(args.budget))))
waivers, notes = load_waivers(wpath)
results, css_read = run_all(page, args, budget)
state_path = Path(args.state) if args.state else None
state = json.loads(state_path.read_text(encoding="utf-8")) if state_path and state_path.is_file() else {}
if not isinstance(state, dict) or not isinstance(state.get("rounds", 0), int):
raise ValueError(f"state file is not a gate state object (delete it to start over): {state_path}")
if state.get("page") not in (None, str(page)): # a state file left by another page starts fresh
state = {}
except json.JSONDecodeError as exc:
print(f"error: bad JSON: {exc}", file=sys.stderr)
sys.exit(2)
except ERRORS as exc:
print(f"error: {exc}", file=sys.stderr)
sys.exit(2)
findings = [f for fs in results.values() for f in fs]
apply_waivers(findings, waivers, notes)
if len(waivers) > MAX_WAIVERS:
findings.append(norm("finish_gate", {"severity": "FAIL", "id": "too-many-waivers", "where": str(wpath),
"message": f"{len(waivers)} waivers: fix instead; more than {MAX_WAIVERS} means the page or the budget is wrong"}))
fails = [f for f in findings if f["severity"] == "FAIL"]
waived = [f for f in findings if f["severity"] == "WAIVED"]
sig = signature([page, wpath, Path(args.budget), Path(args.lexicon)], css_read)
rounds = int(state.get("rounds", 0))
if state_path and state.get("sig") != sig and state.get("status") not in ("done",):
rounds += 1
if args.done:
state.update(status="done", done=args.done.strip())
if state.get("status") == "done":
verdict, code = f"GATE: DONE ({state.get('done', '')}) with {len(fails)} FAIL open", 0
elif not fails:
verdict, code = "GATE: PASS", 0
state["status"] = "passed"
elif state_path and rounds >= args.max_rounds:
verdict, code = f"GATE: OPEN {len(fails)} (rounds used up)", 1
state["status"] = "open"
else:
where = f"round {max(rounds, 1)} of {args.max_rounds}" if state_path else "rounds not tracked; pass --state"
verdict, code = f"GATE: FAIL {len(fails)} ({where})", 1
state["status"] = "fixing"
if state_path:
state.update(rounds=rounds, sig=sig, page=str(page), max_rounds=args.max_rounds)
state_path.write_text(json.dumps(state, indent=2) + "\n", encoding="utf-8")
if args.format == "json":
print(json.dumps({"page": str(page), "verdict": verdict, "rounds": rounds, "fail": len(fails),
"waived": waived, "notes": notes, "findings": findings}, indent=2))
else:
print(f"finish_gate: {page}")
for script, fs in results.items():
nf = sum(f["severity"] == "FAIL" for f in fs)
print(f" {script:<19} {nf} FAIL, {sum(f['severity'] == 'WARN' for f in fs)} WARN, "
f"{sum(f['severity'] == 'WAIVED' for f in fs)} waived")
for f in fails[:40]:
print(f" FAIL {f['script']:<19} {f['id']:<17} {f['where']:<16} {f['text'] or f['message']}")
if len(fails) > 40:
print(f" ... {len(fails) - 40} more FAIL; run the single checkers for the full list")
for f in waived:
print(f" WAIVED {f['script']:<19} {f['id']:<17} {f['where']:<16} reason: {f['reason']}")
for n in notes:
print(f" NOTE {n}")
print(verdict)
sys.exit(code)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |