Guides an engineer building a NEW re-frame2 implementation in one of the eight in-scope JS-cross-compile-to-React+VDOM host languages — ClojureScript (the reference), TypeScript, Melange/ReScript/Reason, F# (Fable), Squint, Scala.js, PureScript, Kotlin/JS. Drives a two-phase workflow (Phase 1: lock decisions; Phase 2: walk the spec corpus in dependency order with the conformance corpus as the acceptance test). Trigger on phrasing like "port re-frame2", "implement re-frame2 in <language>", "second re-frame2 implementation", "implementor checklist", "conformance corpus", or any prompt about building re-frame2 itself. **Do not use** for: writing apps on the CLJS reference (use `re-frame2`), greenfield bootstrap (use `re-frame2-setup`), v1→v2 migration (use `re-frame-migration`), or live-app inspection (use `re-frame2-pair`).
Guides an engineer building a NEW re-frame2 implementation in one of the eight in-scope JS-cross-compile-to-React+VDOM host languages — ClojureScript (the reference), TypeScript, Melange/ReScript/Reason, F# (Fable), Squint, Scala.js, PureScript, Kotlin/JS. Drives a two-phase workflow (Phase 1: lock decisions; Phase 2: walk the spec corpus in dependency order with the conformance corpus as the acceptance test). Trigger on phrasing like "port re-frame2", "implement re-frame2 in <language>", "second re-frame2 implementation", "implementor checklist", "conformance corpus", or any prompt about building re-frame2 itself. **Do not use** for: writing apps on the CLJS reference (use `re-frame2`), greenfield bootstrap (use `re-frame2-setup`), v1→v2 migration (use `re-frame-migration`), or live-app inspection (use `re-frame2-pair`).
This skill is workflow + guidance layered on the spec corpus at spec/. The spec is the contract; the reference impl under implementation/ is one worked example, not normative.
Phase 2 — implement EPs in dependency order (001 → 002 → 006 → 004 → 009 → 015, then optional EPs per Phase 1 scope), validated by the conformance corpus.
Term: EP = Extension Point, a numbered per-area Spec — EP 001 = spec/001-Registration.md, EP 002 = spec/002-Frames.md, etc. The spec calls these "numbered Specs"; this skill uses "EP" because the walking order, dependency graph, and conformance-fixture families are all keyed off the numbers.
When NOT to use this skill
Full skill-disambiguation matrix: skills/README.md §Skill routing — single source. In brief: not for authoring on the CLJS reference, greenfield bootstrap, v1→v2 migration, live-app inspection, or pattern-rationale reading.
Spec is the contract — pinned before reading. When implementation/ and spec/ disagree, the spec wins. The kickoff prompt names a day8/re-frame2 commit/tag; verify the checkout's HEAD and origin before reading the spec and record the pin in DECISIONS.md (preamble before D1). An unverified checkout is not the contract.
Phase 1 before Phase 2. Lock decisions in writing before writing code.
Dependency order. EP 001 → 002 → 006 → 004 → 009 → 015 are the foundation; optional EPs sit downstream. (Spec 015 Data Classification is v1-required — it rides the 009 emission boundary, so it lands right after instrumentation.)
Substrate-agnostic phrasing. Write to "the identity primitive", "the render-tree", "the reactive container" — not to hiccup / Reagent / keywords.
No core.async equivalents. Async effects ride host primitives; cross-frame work is run-to-completion-drained.
JVM-runnability for testing. Pure transitions and pure sub computations must be callable from a non-substrate harness.
Conformance corpus is the acceptance test. Score is passed / claimed-applicable; a fixture you can't make pass without outside sources is a spec gap.
Spec gap → search upstream issues, draft, ask before filing. Don't paper, invent, extrapolate from the reference, or auto-file. Spec gaps reach maintainers via upstream day8/re-frame2 GitHub issues — never via bd. Full workflow + shell-safety recipe (search-first, safe-alphabet title/keywords, --body-file filing, reviewer pass) in references/cardinal-rules.md §8.
Per-issue approval gate for any cross-repo side effect. Before gh issue create against a repo other than the engineer's, show the full draft and wait for explicit "yes" / "go" / "file it". Invoking the skill is consent to the workflow, not to each cross-repo write. See references/cardinal-rules.md §9.
Honour the reserved :rf/* scheme — with the fixed three-fx unqualified carve-out. Framework ids live under the single root :rf/*; user code MUST NOT register there. The fx-ids :dispatch, :dispatch-later, :raise are the carve-out — register/recognise as-is, don't namespace or reject. Full text (runtime-db partition, the :rf.error/legacy-runtime-root hard-error, error ids) in references/cardinal-rules.md §10; reserved-surface catalogue spec/Conventions.md, surface map spec/Ownership.md.
Walk references/phase-1-decisions.md and produce a locked-decision record using the references/decision-record.md template. Eight decision blocks (D1–D7 plus D5b), detailed there: D1 target language, D2 substrate, D3 scope, D4 always-required realisation decisions (Implementor-Checklist Part 2's F1–F6 / S1–S3 / Sub1–Sub2 / V1–V3 / T1–T3 / E1–E2, sub-numbered 1:1 with the checklist), D5 schema mechanism, D5b data classification (v1-required, not D3-gated), D6 integration story, D7 capability tag set. Canonical option matrices: spec/Implementor-Checklist.md.
Output: a single dated decision record committed to the port's own repo.
Phase 2 — walk the spec corpus
With Phase 1 locked, walk references/phase-2-impl-order.md EP-by-EP. Per EP the leaf carries: what to read first, the contract to expose, how the CLJS reference realised it (one example, not normative), what the conformance fixtures check, common spec-gap traps.
Dependency order is fixed: EP 001 Registration → 002 Frames → 006 Reactive substrate → 004 Views → 009 Instrumentation → 015 Data Classification, then a first conformance pass — the required-foundation gate — against every fixture applicable to the three v1-required families (:core/* + :identity/* + :data-classification/*; the exact tags derive from the pinned corpus per references/conformance.md §Capability tagging). (Who runs the gate: references/output-format.md §Discipline — the agent runs a per-EP slice when it can, the full pass stays engineer-owned.) Spec 015 is v1-required, not optional — it overlays the 009 emission boundary (and the MCP wire / Xray / log-sink consumers) with path-marked data classification, so it lands in the foundation right after 009. Optional EPs (010 Schemas, 008 Testing, 005 State machines, 012 Routing, 011 SSR, 013 Flows, 014 HTTP, 007 Stories, 016 Resources) follow in the order Phase 1 declared yes, each gated by its D3 question (Q1 machines, Q2 routing, Q3 SSR, Q4 schemas, Q5 stories, Q8 Flows, Q9 HTTP, Q10 Resources; Q6 Tool-Pair and Q7 AI-Audit gate the non-EP surfaces). Resources is post-v1 and rides Q9 Managed HTTP — its transport lowers onto :rf.http/managed.
Spec 015 Data Classification is implemented (v1-required) as a path-based, fail-open hygiene overlay — full obligation (four declaration surfaces, commit-plane fold, sensitive-wins-over-large, wire-marker-vs-display-sentinel split, fail-closed projection) in references/phase-2-impl-order.md §EP 015 — Data Classification.
The port exposes spec/API.md, adapted to host idiom.
The composition substrate is built around image → frame → event stream (EP-0023) — one registrar, rf/image / rf/make-frame (re-construction folds image hot-reload in — spec/002-Frames.md §Resolved decisions, "Frame-lifecycle facade collapse" — there is no separate reload-images! verb), process-local frame ids, frame-derived resolution; no realm / app / module composition layer to build or conformance-check. Full contract (and the negative list) in references/phase-2-impl-order.md §Composition substrate.
