mizchi

MoonBit code generation and packaging best practices. Use when writing MoonBit code to avoid common AI mistakes with syntax, tests, and benchmarks, or when defining and publishing a Wasm executable with SKILL.md for the MoonBit Skills Marketplace.

Use after a formal model or verifier check already exists and the user wants to maintain it over time. Helps Codex compare specs/docs, implementation code/tests/config/logs, and formal models or CI checks for drift; classify whether the drift is in the spec, code, model abstraction, harness, or unresolved domain decision; run or plan verifier checks; and translate SAT/UNSAT changes, counterexample traces, proof failures, stale models, and CI results into domain-language review questions and ledger entries.

Use when reconciling software specs, docs, tests, configs, code, logs, or incidents with formal methods. Helps Codex extract claims, decide whether docs or implementation are the source of truth, choose an appropriate tool such as Z3, Alloy, TLA+, P, Dafny, MoonBit prove, Lean, Rocq, Why3, Verus, CBMC, Tamarin, or ProVerif, build the smallest useful model, run or plan verifier checks, and translate SAT/UNSAT, traces, proof failures, or proof obligations into domain-language questions and regression guards.

Meta-skill for picking project skills via APM. Invoke ONLY when the user explicitly asks to set up apm.yml, choose which skills a project needs, or evaluate a catalog match — do NOT auto-invoke on routine project-init or apm-management tasks. Two-phase: pick from a curated catalog first; only escalate to broader search/evaluation when the catalog has no fit. Avoids the failure mode of impulse-installing skills you never use or hand-searching GitHub when a vetted answer already exists.

Review screenshots or other images with OpenRouter vision models via bundled Deno scripts. Use for quick VRT sanity checks, invalid-image screening, or CI gates. `scripts/review-image.ts` returns freeform feedback; `scripts/review-image-ci.ts` returns strict `pass|fail` JSON and exits non-zero on fail.

Entry-point for the `@mizchi/vlmkit` toolkit — VLM-driven frontend kit covering visual regression (snapshot / diff / regression-watch), markup synthesis from screenshots, design-token / theme / a11y / i18n audits, and a 2-stage VLM + LLM CSS auto-repair loop. Use when a coding agent has edited HTML/CSS and needs to know whether the visible output changed, where it changed, and which CSS properties drove the change — or when the task is markup-from-image / token / theme audit / fix-loop driven by VLM. This skill orients you to the 5 detailed sub-skills (vrt-visual-diff / vrt-migration-eval / vrt-markup-synth / vrt-regression-watch / vrt-css-fix-loop) and the verb-group CLI; pick the matching sub-skill once the task shape is clear.

ECS blue/green deployment patterns. Recommends ALB-native weighted target groups as the simpler default; covers CodeDeploy as a reference for teams that already use it or need pipeline-integrated rollback. Use when choosing or debugging ECS blue/green infrastructure.

Use when ECS Service Connect の DNS alias が IPv6 アドレスを返し、 IPv4-only の Fargate task から `network is unreachable` / `EAI_AGAIN` 等で接続できない問題に遭遇したとき。 OTel Collector → Tempo の OTLP gRPC、 Fargate → Service Connect の HTTP/gRPC 通信が突然失敗する症状が典型。 ECS / Fargate / Service Connect / OTLP / IPv6 dual-stack 関連の接続障害から起動して良い (user が原因を IPv6 と特定していなくても OK)。

Reference for the `vrt` CLI — Visual Regression Testing combined with accessibility (a11y) semantic verification. Use when running `vrt-test` / `vrt` (Playwright VRT) / `vrt-update` / `vrt compare` / `vrt snapshot`, configuring the fix-loop CSS challenge benchmark, or picking a VLM model for diff analysis.

Turn a natural-language spec into Playwright tests with deterministic, reproducible VRT and a self-healing loop. Uses the official init-agents planner/generator to explore the app and generate tests, a determinism layer to keep screenshots byte-stable, and @mizchi/vlmkit-heal to auto-fix failures. Use when authoring Playwright tests from a spec, making visual regression tests deterministic, getting generated tests to reproduce in CI, or healing tests that drift from the UI.

Closed-loop CSS auto-repair. Given a fixture with a known regression (one CSS property or one selector block removed), iterate with a VLM that proposes the missing fix from the diff screenshot, apply it, and re-run until the diff falls below a threshold. Currently scoped to the CSS-challenge fixture set in `src/experiments/css-challenge/`; adapting to an arbitrary repo requires writing a fixture entry. Use when measuring whether a VLM model can recover a known regression, not for production self-healing.

Run vrt diff in a stateful loop where each run is compared against the previous run's persisted summary, surfacing a `⚠ REGRESSION` banner when the majority of viewports get worse. Designed for periodic CI gates (per-PR or scheduled) where you want "did this change make things worse" as a binary signal, not a one-shot snapshot. Stores summary at `.vrt/last-diff-for-agent.json` by default.

Compare two rendered pages (URL pairs or local HTML) and produce a structured Markdown report tailored for coding agents — pixel diff per viewport, per-section diffRatio, computed-style diff split into universal vs. breakpoint-gated, and worst-viewport screenshot paths. Use when the agent just made a UI change and needs to know whether it altered visible output, where it altered it, and which CSS properties drove the change. Works on a single HTML/URL pair without baseline state.

Evaluate whether a framework / CSS-library / build-system swap (Tailwind → vanilla CSS, reset-css switch, bundler swap, etc.) produced a visually-equivalent result. Three modes — compare (deterministic pixel + CSD), blind (agent runs without baseline reference), subagent (dispatched-agent verification) — let the caller pick the rigour level. Use when the diff is large by construction (the markup was rewritten) and a flat pixel diff would drown the actual regressions in noise.

Five DOM/pixel-based signal tools for markup work — turn a screenshot + HTML scaffold into a converging pixel diff (build component), crop a page screenshot into per-component PNGs (scan component), audit hard-coded values against a design-token scale (check tokens), verify theme parity (check theme — light vs dark render), and stress-test layout under inflated text (stress i18n). All five are pure DOM + Playwright + pixel processing — **no VLM / no API key required**. The agent supplies the markup reasoning; the tool surfaces the signal. Use when you've authored HTML/CSS and want signal back without paying VLM latency or cost.

Improve a developer-facing tool (CLI, library, agent harness) by running closed-loop validation with disposable subagents, treating their friction as the deliverable, fixing the friction, and re-running. Use when the user wants to evaluate or harden a tool whose value depends on whether an agent can use it — vrt-like signal loops, agent SDKs, CLI ergonomics, prompt scaffolding, IDE integrations. The loop produces both a stronger tool and a written record (per-run reports + tracked issues) of what was learned and why.

Use when scaffolding a new standalone CSR app that uses luna (@luna_ui/luna) outside the luna.mbt monorepo — running `npx @luna_ui/luna new`, choosing TSX vs MoonBit, or fixing a broken `--mbt` scaffold (moon build `_bench` import error, or vite `failed to resolve import "mbt:..."`).

Use when running `sol new` for the first time, when `sol <subcommand>` fails with `failed to resolve path mizchi/sol/cmd/sol_js` / `Run this command inside a MoonBit project that depends on mizchi/sol.`, or when moving from `sol dev` to `sol build` / `sol serve` for the first time. Covers (a) the bootstrap rules — `sol new <name> --user <ns>` works in an empty directory as of sol 0.22.2, but `--cloudflare` / `--doc` / `--dev` still need a host moon project, and every non-new subcommand needs `.mooncakes/mizchi/sol/` locally (= `moon install` after `sol new`) — (b) the sol 0.22.x scaffold layout (`app/server/routes.mbt` holds routes + page handlers; `app/layout/` is a separate package; `/` and `/about` are pre-registered) and (c) the production flow gotchas (`sol build` writes to two directories, `sol serve` does NOT rebuild, dev & prod both default to :7777).

Page description for <meta>

Use whenever working with `mizchi/luna` in the luna.mbt repo — writing CSR examples, fixing reactivity bugs (effects re-running on unrelated signal changes), adding new luna features, or onboarding to luna's mental model. This is the unified entry point; pick the right reference page below for the specific situation.

Use when running Playwright tests in this repo (luna.mbt) and either the test fails to discover specs ("did not expect test.describe()" / "two different versions of @playwright/test") or you're adding a new playwright config under astra/ or sol/. Captures the version-skew between root and per-package @playwright/test pins.

Use when deploying sol_app (or any sol-built MoonBit SSR worker) to Cloudflare Workers, debugging error 10021, or extending sol/examples/sol_app/scripts/patch-cloudflare-globals.mjs. Captures the global-scope I/O traps in MoonBit core + sol's generated bundle and the wrangler ASSETS binding URL layout.

Detect duplicate MoonBit code using AST-based similarity analysis. Use when working with .mbt files and looking for code duplication, refactoring opportunities, or enforcing code quality.

Detect duplicate Python code using AST-based similarity analysis. Use when working with .py files and looking for code duplication or refactoring opportunities.

Detect duplicate Rust code using AST-based similarity analysis. Use when working with .rs files and looking for code duplication or refactoring opportunities.

Detect duplicate code using AST-based similarity analysis. Auto-selects the right tool based on file types in the project (similarity-ts for TypeScript/JavaScript, similarity-py for Python, similarity-mbt for MoonBit, similarity-rs for Rust, etc).

Detect duplicate TypeScript/JavaScript code using AST-based similarity analysis. Use when working with .ts/.tsx/.js/.jsx files and looking for code duplication or refactoring opportunities.

Add a new test-result adapter to flaker (parses an external report format into TestCaseResult[]). Use when the user asks to "add a flaker adapter for <X>", "make flaker import <some format>", "support <some test runner> in flaker import", or otherwise extends `flaker import --adapter <name>` with a new format. Encodes the file layout, registration step, test pattern, CHANGELOG convention learned from the chaosbringer adapter (#79).

Cut a flaker patch/minor release manually — branch → bump 3 version sites → CHANGELOG → PR → merge → tag → GitHub release → publish.yml OIDC publish. Use when the user asks to "release flaker N.N.N", "bump flaker", "publish flaker", or runs the equivalent in 日本語 ("flaker をリリース", "patch bump"). MAINTAINER-ONLY — only the npm OIDC trusted publisher (mizchi) can complete the publish step. Does NOT apply to chaosbringer (release-please) or other repos.

Operate @mizchi/flaker after setup. Use when the user asks how to run flaker day-to-day, review sampling and flaky metrics, design advisory vs required CI gates, promote or demote Playwright E2E or VRT checks, tune PR time budgets, run nightly triage, or manage quarantine and `@flaky` tags in an OSS repository. Targets @mizchi/flaker 0.7.0+ (declarative apply model).

Set up @mizchi/flaker on a new repository. Use when the user asks to introduce flaker, configure flaker.toml, integrate flaker into GitHub Actions, or "start using flaker on this project". Encodes the declarative apply-based onboarding flow for @mizchi/flaker 0.7.0+ (declarative apply model).

Use this skill when adding or updating the dependency-analysis example in this repository, including workflow.star design, changed-path target selection, and executable validation with moon run.

プロジェクトに actrun を導入する。インストール、actrun.toml 設定、ワークフロー調整をガイドする。

actrun (ローカル GitHub Actions ランナー) の使い方リファレンスとワークフロー実行支援。actrun コマンドの提案、ワークフロー解析、実行プラン確認を行う。

actrun の実行失敗を診断する。ログ解析、エラー原因特定、修正提案を行う。

`vibe new` から `vibe shell-stdin --restore` で scratch-db を積み上げ、`finalize`/`normalize`/`apply` まで安全に回すための実践手順。

vibe compiler の性能改善手順 — node --cpu-prof での実コンパイルのプロファイル取得、phase bench (__bench_ export) の実行、ホットスポットの読み方、修正→fixpoint→回帰の検証ループ。コンパイルが遅い・CI が遅い・bench の退行を調べるときに使う。

backend(gc/linear/RC)でコンパイルしたコンパイラ自身が誤動作するとき、probe entry の追記とフェーズ二分で miscompile を特定する手法。コンパイラの self-compile が hang する・誤った診断を出す・出力が linear と食い違うときに使う。

Use when modifying the TypeScript-to-MoonBit bridge generator in this repo — `src/bridge/`, the `ts2mbt` CLI (generate / vendor / scaffold / package / bridge / ffi / decl), `bridge.mbti` / `bridge.mbt` / `bridge.js` synthesis, or the companion vite-plugin-moonbit integration.

Use when modifying `mbt2ts normalize` (the MoonBit-generated `.d.ts` rewriter), `src/bridge/typescript_decl.mbt`, or the experimental normalizedDts integration in vite-plugin-moonbit.

Use when working on github.com/mizchi/pkspec, especially release readiness, version bumps, GitHub Actions/Nix release checks, adapter DSL work, or the experimental Playwright/Vitest coverage presets. Covers the repo's spec gates, pkfire release flow, pkl CLI dependency gotchas, and what is intentionally still experimental.

Moonbit cheatsheet to check syntax and corelibrary usages

Profile MoonBit memory/allocations with moon-pprof to find and fix allocation hotspots. Use when the user wants to memory-profile a MoonBit package, reduce allocations / GC pressure, investigate a slow hot path on the wasm backend, or mentions moon-pprof / samply / "memory profile" / "allocation profile" in this repo.

Explain, operate, and troubleshoot `pkf`, the pure-MoonBit CLI for the pkfire typed task runner, and author or maintain its `Taskfile.pkl` files. Use when a user asks what pkf is, wants to inspect or run a task graph, add cached tasks or services, model affected-file workflows, migrate from just/Make/Taskfile.yml, diagnose Pkl package or cache behavior, or change pkfire itself. This skill distinguishes the current MoonBit implementation from stale Go-era documentation and records the exact schema, action-key, service, and CLI contracts.