freminal

Use ONLY when working in the freminal repository AND touching the rendering pipeline, PTY I/O, buffer operations, ANSI parser, or `build_snapshot()`. Names exactly which benchmark file and benchmark IDs cover each performance-sensitive area of freminal. The generic before/after procedure, regression threshold, and recording format live in the shared `performance-benchmarks` skill — this skill is the freminal-specific catalog that skill points back to.

Use ONLY when working in the freminal repository AND about to open a pull request, finalize a change, or declare a task done — especially any change touching `#[cfg(windows)]` / `#[cfg(target_os = "windows")]` code, the vendored `portable-pty` crate, cross-platform path or filesystem logic, threads/closures/`Send` bounds, or anything else that compiles differently on Windows. Mandates running `cargo xtask check-windows` (clippy for the x86_64-pc-windows-gnu target) before the PR, so Windows-only compile errors and lints are caught locally instead of only on the `windows-latest` CI job. Also states what this gate does NOT catch (runtime failures) and where those are caught instead.

Use ONLY when working in the freminal repository AND changing task or version status in Documents/MASTER_PLAN.md — most importantly when a task's PR merges, when starting a task branch, or any time you edit MASTER_PLAN.md. Codifies the one-directional status lifecycle (Stub/Planned -> In progress -> Pending merge -> Complete), the mandatory merge-time transition that gets forgotten, the two-tables-must-agree invariant (Task Summary Status column vs. Completion Tracking dates), and the main-lag caveat for long-running integration branches like v0.11.0-kitty.

Use ONLY in the freminal repository when activating a version from MASTER_PLAN.md whose plan document is a stub (no per-subtask breakdown), or when fleshing out / decomposing any version's tasks into implementable subtasks. Codifies the just-in-time planning policy (don't decompose far-future versions; flesh a version out at activation against the real code), the Sonnet-sized subtask shape (scope, deliverable, verification, prohibitions, stop condition), and the Opus-orchestrates / Sonnet-implements / Opus-reviews division of labour. Pairs with freminal-orchestrator-protocol (planning-time companion to that execution-time skill).

Use ONLY when working in the freminal repository AND adding, editing, or debugging a GUI modal, dialog, overlay, popup, or any in-window widget that contains a focusable input (a TextEdit, search box, name field, filter box, etc.). Triggers on "my dialog doesn't accept typing", "focus bounces back to the terminal", "the modal renders but I can't type in it", "Escape/Enter does nothing in the dialog", or creating a new egui::Window/Area on the terminal surface. Codifies the ui_overlay_open registration + lock_focus(true) + per-frame request_focus pattern that every working modal uses, and that every new modal forgets.

Use ONLY when working in the freminal repository AND adding, renaming, or removing a configuration option (a field on `Config` or any of its section structs in `freminal-common/src/config.rs`, e.g. a new `[notifications]`/`[command_blocks]` key or a whole new section). Codifies the mandatory wiring checklist that prevents the "user sets it in config.toml but it silently does nothing" bug class — the `ConfigPartial` / `apply_partial` omission that dropped `[notifications] enabled = true` (fix 76.4a).

Use ONLY when working in the freminal repository (the Rust terminal emulator at ~/GitHub/freminal with crates freminal, freminal-terminal-emulator, freminal-buffer, freminal-common, freminal-windowing, xtask). Triggers on architecture-affecting changes: anything touching the GUI/PTY split, the ArcSwap snapshot transport, the channel-based input system, crate dependency boundaries, or `TerminalEmulator` / `TerminalSnapshot` / `ViewState`. Codifies the post-refactor lock-free architecture invariants.

Use ONLY when working in the freminal repository AND changing the ANSI parser, terminal handler, or renderer in a way that adds, removes, or alters support for an escape sequence (C0/C1, ESC, CSI, OSC, DCS, APC, DEC mode, standard mode, charset, or renderer-side consumption). Mandates the dual-document update: ESCAPE_SEQUENCE_COVERAGE.md (status table) and ESCAPE_SEQUENCE_GAPS.md (gap roadmap), with the "Last updated" header and Planned column maintenance.

Use ONLY when working in the freminal repository AND analyzing files produced by `--recording-path` (the `.frec` or `.bin` files emitted by the FREC recorder). Forbids writing ad-hoc parsers or one-off python scripts for binary frec files; mandates use of `sequence_decoder.py` at the repo root, which supports filtering, escape decoding, timing, and topology events.

Use ONLY when working in the freminal repository AND writing or reviewing Rust code that converts between numeric types (usize, u32, i32, f32, f64, etc.). Codifies the "no raw `as` casts in production for numeric conversions" rule and mandates the `conv2` crate's `ValueFrom` / `ValueInto` / `ApproxFrom` / `ApproxInto` traits.

Use ONLY when working in the freminal repository AND about to spawn sub-agents to decompose a task. Codifies the mandatory action-class scoping protocol for sub-agent prompts -- READ-ONLY, CODE-REVIEW, IMPLEMENTATION, COMMIT -- with explicit scope, deliverable, prohibitions, and stop condition in every spawned prompt. This is the single most important orchestration rule in the freminal repo; ignore it and sub-agents go off-script.