🌐 Website: https://wohsj110.github.io/mini-app-spec/ · skills.sh: https://www.skills.sh/wohsj110/mini-app-spec/mini-app-spec
An agent skill that turns messy, multi-source requirements (PRD / BDD / Figma / code) into a single self-contained mini-app-spec.html — an executable specification that embeds a machine-readable contract, an operable prototype, a state-machine canvas, BDD acceptance scenarios, an annotation/review loop, and verifiable run evidence. After implementation, the same artifact is used to reconcile what was built against what was agreed.
It is designed for AI coding agents (Claude Code, Codex, Cursor, …): the agent produces and maintains the spec through a locked-down CLI pipeline, and a validator makes it mechanically hard for the agent to cheat.
This skill is a hardened implementation of the idea in Matt Rickard's essay The Unreasonable Effectiveness of Mini Apps as Specs: instead of a static document that drifts from reality, ship the spec as a tiny interactive app that stakeholders can click through, annotate, and hold the implementation accountable to.
On top of that idea, this skill adds what a document can't have:
- A machine contract as the single source of truth — flows, states, transitions, Gherkin scenarios, and verification methods live as structured JSON inside the HTML, not as prose.
- Derived status is computed, never stored — nobody (human or AI) can hand-write
passed. A scenario's status is derived from evidence, or it isnot-run. - Evidence, not claims — verification commands are frozen at a gate, executed by the tool itself (
record-run), and their outputs are hashed into a ledger. - A review loop that survives — pin-style annotations anchor to stable IDs, export as structured change tickets, and block acceptance until adjudicated.
mini-app-spec.html ← the deliverable: open it by double-click, no server
├── render engine (stateless, versioned, business-agnostic)
├── <script id="mini-app-contract"> ← machine contract = SSOT
├── <script id="mini-app-ledger"> ← runs / evidence / annotations / acceptances
├── <script id="mini-app-stamp"> ← envelope: per-block hashes, revision chain
└── <template id="ui-ST-*"> ← declarative, zero-JS prototype screens
| Layer | Role | Rule |
|---|---|---|
mini-app-spec.html |
The database. Contract + ledger + templates in one file | Never hand-edited |
scripts/spec.mjs |
The only write path. Every mutation is a validated transaction | Validator fails → nothing is written |
assets/template.html |
The stateless render engine | Business never modifies it; upgrades via save --retemplate |
The full field contract, revision semantics, state algebra, judges, and template allowlist are authoritatively defined in references/contract.md.
- The contract can only be written through
save. Out-of-band edits are caught by the envelope hashes and byvalidate --against-git(replay detection anchored to git gate commits). - Derived status is computed, never stored. Hand-written
passedis a validator error. - Verification is executed by
record-runitself — the agent supplies commands, never results. Commands are frozen at a verification gate; behavior semantics are fingerprinted at flow alignment, so changing aThensilently invalidates old evidence. - Acceptance must quote the user verbatim and pass six hard preconditions (fresh source-observation batch, zero pending annotations, per-scenario waivers for anything non-green, …).
Threat model: careless mistakes, lazy shortcuts, and hallucination — not a malicious agent. The last line of defense is always a human looking at evidence at the final stop point.
collect sources → map flows ─🛑 STOP ①: user confirms flow list & risk tiers
↓
align flow-by-flow (states / transitions / scenarios / prototype) ⏸ user reviews each flow
↓
implementation happens outside this skill
↓
freeze verification commands → record-run per scenario ─🛑 STOP ②: user inspects evidence → accept
The artifact renders four views: Flow Overview (merged map + SVG state machine on an infinite pan/zoom canvas), Prototype (a living phone screen with real-time state chips, live values, memory-vs-persisted dataflow, and an event log), Scenario Acceptance (filterable cards that jump into the prototype), and Run Evidence. An annotation layer (📌 click-to-anchor, Figma-pin style) works across all views.
Requirements: Node ≥ 18, git (artifacts must live inside a git repository).
# One-liner via the skills CLI (auto-detects Claude Code / Codex / Cursor; add --global for user-wide)
npx skills add wohsj110/mini-app-spec
# Or plain git clone
git clone https://github.com/wohsj110/mini-app-spec ~/.claude/skills/mini-app-spec
# Self-test: 20 fixture cases + 32 injection/attack cases must all pass
node ~/.claude/skills/mini-app-spec/scripts/run-fixtures.mjs
node ~/.claude/skills/mini-app-spec/scripts/run-injections.mjsInstall and verify the "mini-app-spec" agent skill:
1. Run: npx skills add wohsj110/mini-app-spec --yes
(target a specific agent with --agent claude|codex|cursor; add --global for a user-wide install)
2. Verify the install — both self-test suites must print ALL PASS:
node <install-dir>/scripts/run-fixtures.mjs # 20 cases
node <install-dir>/scripts/run-injections.mjs # 32 cases
3. Read <install-dir>/SKILL.md before first use. Rules that matter:
- Artifacts live at docs/mini-app-spec/<feature>/mini-app-spec.html, inside a git repository.
- All writes go through: node <install-dir>/scripts/spec.mjs <command> …
- Never hand-edit the artifact HTML; edit via extract → modify JSON → save.
Then, inside any project, ask your agent to use the skill — or drive the pipeline directly:
node <skill>/scripts/spec.mjs new docs/mini-app-spec/my-feature/mini-app-spec.html --id my-feature --title "My Feature"
node <skill>/scripts/spec.mjs extract docs/mini-app-spec/my-feature/mini-app-spec.html # contract out as JSON
node <skill>/scripts/spec.mjs save docs/mini-app-spec/my-feature/mini-app-spec.html --data payload.json
node <skill>/scripts/spec.mjs validate docs/mini-app-spec/my-feature/mini-app-spec.html --strict
node <skill>/scripts/spec.mjs status docs/mini-app-spec/my-feature/mini-app-spec.html # resume briefing| Command | Purpose |
|---|---|
new |
Create an empty artifact from the pinned engine |
extract / save [--expect-revision] [--gate <name>] [--retemplate] |
The only round-trip for editing the contract; --gate also creates a git replay anchor |
validate [--strict] [--against-git] |
Full rule check; must be 0 errors before review or acceptance |
status |
Read-only resume briefing (never collapses the status tuple) |
confirm-command --scenario --command |
Verification gate: freeze the command |
record-run --scenario |
Execute frozen command, judge output, write hashed evidence |
refresh-sources |
Observe all registered sources as a batch (required before acceptance) |
merge-feedback --data / annotate --id --status |
Merge exported annotation tickets / record user adjudication |
accept --verbatim "…" |
Write the acceptance fact (six hard preconditions enforced) |
recovery --reason |
Rebuild from the last trusted git gate baseline |
export-md |
Portable read-only Markdown export (the HTML stays authoritative) |
| kind | What it checks |
|---|---|
assert |
Structured test results (JUnit XML), testCount > 0 and all green |
db |
Frozen read-only query + numeric predicate over its output (device context required) |
file |
File-tree reconciliation: declared paths/globs all exist |
grep |
Pattern count predicate over files — counts only, never logs matched values (secret-safe) |
The skill runs fully standalone, but it pairs best with these open-source skills from mattpocock/skills:
| Stage | Skill | What it adds |
|---|---|---|
| Before — explore | wayfinder |
Map work too big for one session into a shared investigation map before touching the requirement |
| Before — requirements | grill-with-docs |
Interrogate a fuzzy idea into a written requirement doc with every decision on record |
| During alignment | grill-me |
One-question-at-a-time interrogation (with a recommended answer each time) for strings of high-impact decisions |
The recommended pipeline:
/wayfinder explore the territory
→ grill-with-docs: interrogate the idea into a requirement doc
→ mini-app-spec: register the doc + Figma frames (via Figma MCP) as sources, build the spec flow by flow
→ escalate high-impact decision strings to grill-me during alignment
Without any of them installed, the skill degrades gracefully to built-in leaning multiple-choice questions.
SKILL.md # the operating manual an agent loads (kept minimal)
references/contract.md # authoritative contract: fields, state algebra, validator rules
scripts/spec.mjs # zero-dependency CLI: the only write path
scripts/run-fixtures.mjs # 20 validator fixture cases
scripts/run-injections.mjs # 32 end-to-end injection/attack cases
scripts/fixtures/ # good & deliberately-broken artifacts
assets/template.html # the stateless render engine
evals/ # fresh-agent behavioral evals + input fixtures
agents/openai.yaml # interface metadata for non-Claude agent runtimes
2026-07: the first real production requirement (a P0 mobile-app feature) went from intake to fully aligned spec in ~40 minutes including live review Q&A: 5 flows, 17 BDD scenarios (manual / db / grep judges), 4 user adjudications recorded verbatim into the contract. Building the state machine surfaced one self-contradiction inside the PRD and three naming inconsistencies across PRD / Figma / history copy — before a single line of code was written. Reconciliation (STOP ②) runs after implementation; this section will be updated with the full-loop reading.