Mini-App Spec

Software requirements often drift from implementation, leading to broken acceptance criteria and "stale" documentation. This skill enforces a Single Source of Truth (SSOT) by generating a self-contained, executable HTML5 specification that acts as a machine contract, operable prototype, and BDD test suite. It bridges the gap between Figma designs and code, ensuring every feature is verified against a frozen behavioral fingerprint before acceptance.

What it does

• Executable Contract Generation produces a mini-app-spec.html containing state machines, BDD scenarios, and embedded prototypes.
• Automated Verification Gate freezes commands and collects evidence per scenario to prevent hand-waived passing status.
• Multi-Source Reconciliation maps requirements from PRDs, Figma (via MCP), and code into unified vertical user flows.
• Interactive Review Sessions launches a local browser session where users annotate the UI directly to generate structured change tickets.
• Mechanical Rule Enforcement blocks acceptance unless specific preconditions, like zero proposed annotations and valid source batches, are met.

How it works

1. Resume or Initialize: Use status to recover context or new to create a fresh artifact from the stateless engine template.
2. Decompose and Map: Register sources and decompose requirements into tiered flows, followed by a mandatory confirmation gate.
3. Align and Prototype: Fill in states and transitions, then open the artifact for visual alignment and fingerprint freezing.
4. Reconcile and Accept: Run record-run to collect evidence, then accept with verbatim user confirmation to stamp the final gate.

Frameworks & tools

The system uses a Node.js CLI spec.mjs for all contract writes and a stateless HTML5/CSS/JS engine. It integrates with Git for replay anchors and recovery, supports Figma via MCP, and enforces CSP-compliant, zero-dependency templates.

Why this beats prompting it yourself

Generic prompts fail to maintain state across long implementation cycles and allow "status cheating" where AI claims success without evidence. This skill uses a mechanically enforced validator and git-anchored replay anchors to ensure the spec and implementation never diverge.

Use cases

• Documenting complex multi-state UI components that require high-fidelity prototyping.
• Auditing legacy codebases by reconciling existing behavior against new BDD requirements.
• Managing stakeholder sign-off with an operable, annotated "live" specification.
• Generating verifiable evidence for compliance-heavy features where manual testing is insufficient.

Known limitations

Requires a Git repository environment to function. The engine forbids external CDNs or heavyweight frameworks; all visual interactions must be self-contained within the HTML artifact.