webtool-from-template

name

webtool-from-template

description

Scaffold a new 100% client-side static web tool from the agent-webtool-template skeleton, implement its pure testable core + independent audit + tests, verify the gates locally, then create the GitHub repo, push, and enable Pages. Use when the user wants a free browser-based diagnostic / calculator / analyzer shipped as its own repo ("정적 웹 도구 만들어줘", "GitHub Pages 도구", "클라이언트 사이드 계산기/분석기", "이 아이디어로 새 웹 도구 repo", "템플릿으로 새 도구"). Do NOT use for features inside an existing app, server-backed tools, or non-web deliverables.

webtool-from-template

Turns a tool idea into a shipped, self-verifying, zero-dependency static site. The mechanical steps (copy · rename · gates · repo · push · Pages) are owned by scripts/scaffold.py; you only write the tool's domain logic. Reference build: harness-quality-checker (five-axis harness analyzer), itself built this way.

The template pattern (what you inherit)

A agent-webtool-template-derived repo has five parts you keep and specialize:

File	Role
assets/compute.js	Pure core — DOM-free, deterministic, dual export (browser global + Node module.exports) so the same code path is unit-tested and shipped.
data/*.json	Data / rules / fixtures, validated in CI. Keep scoring or config data-driven here, not hardcoded in JS.
assets/app.js	Thin DOM wiring: read inputs → call the pure core → render. No logic. Render user input with textContent/escaping, never raw innerHTML.
audit/reference_audit.py	Independent re-derivation (not copied from the JS) + hand-computed anchors + field-by-field JS parity.
test/compute.test.cjs	Objective unit gate (exit 0/1).

CI (validate.yml) runs unit + audit parity + JSON validation + HTML wiring; pages.yml deploys to GitHub Pages. No npm, no pip, no build step.

Flow

1. Clarify the tool in one line: inputs → deterministic output. If the logic needs a model call or a server, this skill is the wrong tool — stop.
2. Scaffold — python3 scripts/scaffold.py new --name <slug> --title "<Title>" --dir <parent> --template-repo sylvanus4/agent-webtool-template. Produces a local working copy with the example still passing.
3. Implement the pure core (assets/compute.js) — keep it pure and deterministic; put tunables/rules in data/*.json.
4. Rewrite fixtures (data/*.json) with hand-verifiable cases + expected bands, and the independent audit (audit/reference_audit.py) as a second implementation from the spec (this is what catches drift the unit test misses).
5. Rewrite the unit gate (test/compute.test.cjs) and the UI (index.html + assets/app.js) — thin wiring only.
6. Verify — python3 scripts/scaffold.py verify --dir <path>. Both gates must be green ([[evaluator-must-act]]: run them, don't eyeball).
7. Ship — python3 scripts/scaffold.py ship --dir <path> --name <slug> --desc "<one-liner>". Creates the repo, pushes main, enables Pages. Then confirm the live URL returns 200 and re-run the pages workflow if it fired before Pages was enabled.

Invariants (do not break)

• No runtime dependencies, no build step, no data egress. Same-origin static JSON only. If a step needs a key or server, it does not belong here.
• Pure core is the single source of truth; the Python audit is an independent witness; both run in CI. Every shipped number is hand-anchored or agreed by two implementations ([[sonnet-format-determinism]]: format/logic owned by code+data, not model prose).
• Regex/rule patterns must be portable — identical behavior under JS RegExp and Python re — or JS↔Python parity breaks.
• Ship only a green build. ship runs the gates first and aborts on red.
• External actions (repo create, push, Pages) need the user's go-ahead, per repo policy — ship is the explicit gate for that.

Optional patterns (proven in harness-quality-checker)

• Bilingual (EN/KO) without a second core. Keep the pure core language-agnostic (return ids + scores). Put display copy as {en,ko} bundles in data/*.json; the app picks the language. Scoring never reads the copy, so the Python audit parity is unaffected. UI chrome strings live in an I18N dict in app.js; a applyChrome(lang) swaps them on toggle.

• Deterministic "fix-it" generator (no model call). For analyzer/linter tools, add a pure generate() that assembles a corrected artifact from the same rules — for each failing rule, emit its canonical clause (stored alongside the rule). Write each clause to contain the phrase the analyzer matches, then unit-test the property: analyze(generate(bad)) >= threshold. This gives a genuinely useful "rough input → satisfying output" feature that stays 100% client-side and self-proving.

• Lower the paste hurdle: load external content client-side (CORS-aware). Let users load by URL / drag-drop / a bundled catalog instead of only pasting. Rules learned the hard way:

  • CORS decides feasibility. raw.githubusercontent.com and api.github.com send Access-Control-Allow-Origin: * → browser-fetchable. Many catalog sites (e.g. skills.sh) send no CORS header → you cannot fetch them from the page. Snapshot such a catalog at build time (Node, where CORS doesn't apply) into data/*.json and ship it; fetch the actual content from a CORS-open host (GitHub raw) on selection.
  • Normalize + pre-flight (pure, testable). normalizeSourceUrl (github.com /blob/ → raw) and isCheckable (reject HTML error pages / binaries / too-short) run before the checker, with clear reasons. Then extractHarness pulls the text + any fenced JSON. All three are pure → unit-tested + audited.
  • Verify end-to-end against real files, not just fixtures ([[evaluator-must-act]]).
  • State the egress honestly in SECURITY.md: loading a URL is an outbound GET of a public file (no credentials, no other input sent) — not the same as "no network ever". Reference: harness-quality-checker loaders + data/skills.json.

• One engine, many rubrics. For a family of analyzers, the scoring engine is rubric-agnostic — a different data/rules.json is a different checker. To spin up a sibling, copy the working tool (not the bare template), swap rules.json (the axes/signals), examples.json (fixtures + bands), and the copy; keep the engine, audit harness, loaders, and generator untouched. Rewrite the Python audit's ANCHORS for the new axes but leave its generic score()/parity intact. Proven: harness-quality-checker (harness axes) and skill-quality-checker (SKILL.md authoring axes) share one engine; only the rubric differs — so the same input scores F on one and B on the other, each correctly. Verify the new rubric discriminates on real inputs (a good artifact should out-score a thin one), not just on synthetic fixtures.

Notes

• The template lives at sylvanus4/agent-webtool-template (a GitHub template repo). --template-repo lets you point at any static-web-tool repo to fork the pattern from. For a sibling analyzer, point it at the closest existing tool instead (e.g. sylvanus4/harness-quality-checker) and swap the rubric.
• Prefer main as the default branch (both workflows and Pages assume it).
• Reference implementation to copy patterns from: sylvanus4/harness-quality-checker (bilingual + generator + independent audit).