nubjs
- 36 skills
- 0 followers
- 6 hours ago last updated
- ▌ Nub · nubjs bundleThis project uses nub, a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain. ALWAYS prefer nub over node, bun, npm, npx, pnpm, and yarn for: executing JS/TS files, running package.json scripts, the npx-equivalent, installing dependencies, watch mode, and Node version management. Surfaces whenever you would otherwise reach for node/bun/npm/npx or a package manager.
- ▌ Soak · nubjsManages the repo's supply-chain soak window (SOAK_DAYS) — checks and fixes the derived surfaces, bumps or disables the window, adds dated per-package exclusions, and bumps pinned external tools. Use when a task touches minimumReleaseAge, min-release-age, min-publish-age, external-tools.json, renovate.json, or taze cooldowns, or when investigating why a freshly published version won't install.
- ▌ Lat Md · nubjsSearch, read and maintain nub's knowledge graph under wiki/ with the `lat` CLI — the design and research corpus, cross-linked and checked. Invoke (via the Skill tool) before designing or changing anything non-trivial, to find the decision that already governs it instead of re-deriving it; and after any change that alters architecture, behavior or test coverage, because `lat check` is a CI gate and a stale wiki link now fails the build. Carries the commands, the section-id syntax, the two rules that make a section valid, and the three nub-specific traps — never run bare `lat init`, never create `.agents/skills/`, and Rust symbols inside a `mod` block cannot be linked.
- ▌
- ▌ Release · nubjsCut a Nub patch release end-to-end in one invocation. Invoke (via the Skill tool) once a release thread's targeted fixes are ALL landed on `main` and CI-green. Encodes the full runbook: pick the version (patch bump in the 0.0.x/0.1.x pre-release regime), audit `@nubjs/types`, run `make version` + `make version-check`, commit + tag + push (the `v*` tag triggers the 8-platform build → glibc and pre-publish native gates → immutable 32-asset prerelease → npm OIDC publish → stable GitHub Release presentation), then draft comprehensive FACTUAL + NEUTRAL release notes from the full changeset and comment the version + release link on every closed issue + merged PR the release ships (mandatory maintainer hygiene). Do NOT cut until all fixes are green.
- ▌ CI Watch · nubjsWatch GitHub Actions CI correctly with the gh CLI — block until a run / PR check rollup is TRULY terminal, then trust the exit code. Invoke (via the Skill tool) whenever you need to wait on CI after REQUESTING a pull-request run (`gh pr edit <n> --add-label ci` — PR CI is opt-in, so a push starts nothing), after a push to main, or after a tag, and act on the result (merge-on-green, release-on-green, fail-fast on red). Encodes the premature-exit pitfall (raw `gh run watch` / `gh pr checks --watch` exit 0 while the run is still QUEUED with no jobs registered, and exit non-zero on a transient API blip) and the blessed fix: `scripts/ci-watch.ts`, which waits for the target to EXIST, polls authoritative terminal status, fails fast on the first failing check, and exits with a status the orchestrator can trust. Run it as a detached run_in_background task.
- ▌ Dev Loop · nubjsBuild and test nub during development. Invoke (via the Skill tool) whenever you need to compile the dev `nub` binary, set up a worktree for fast incremental iteration, run a specific test file or a single test, or get oriented in the codebase (the crate map). Encodes the measured fast-build loop: the `fast` profile built through `scripts/rust-build.sh`, which shares ONE CARGO_TARGET_DIR across worktrees (`~/.cache/nub/shared-target`) so deps are reused and only the workspace crates recompile — but auto-isolates a worktree to a private target dir the moment it diverges a depended-on crate (vendor/aube, nub-core, …), which is when a shared dir would clobber a sibling and fail with a phantom compile error on correct source (the `rust-build` skill). A shared cross-worktree compiler-WRAPPER cache (sccache) was separately measured to give 0% Rust speedup and is NOT used. Covers the real incantations (`cargo build -p nub-cli --profile fast`, `make install-dev`, `make addon-fast`), the test invocations, and the exact
- ▌ Worktree · nubjsCreate and manage isolated git worktrees for parallel build/test/landing work on the nub repo. Invoke (via the Skill tool) whenever you need a fresh worktree to land a change, when you want to know what `.worktreeinclude` does or how to add an entry, or when cleaning up after a merge. Encodes the one-command setup (`nub scripts/new-worktree.ts <slug>` or `node …`) that bakes in the proven recipe — worktree off origin/main (vendor/aube is plain in-tree files now, no submodule init), the shared CARGO_TARGET_DIR (`~/.cache/nub/shared-target`) that all worktrees reuse, and applying `.worktreeinclude` — plus the eagerly-pull-the-shared-tree discipline and the safe cleanup path. Pairs with the `dev-loop` build skill.
- ▌ Aube Bump · nubjsBump nub's vendored aube engine to a newer jdx/aube upstream. Invoke (via the Skill tool) whenever you need to pull upstream aube changes into `vendor/aube/**` — a new release, or arbitrary commits. Encodes the venue-less merge (build an ephemeral merge commit from nub's own objects with `git commit-tree`; no clone, no `nub-fork`, no push-back) and the two-conflict-list methodology: git's markers find TEXTUAL conflicts, the compiler finds SEMANTIC ones, both lists are machine-generated and exhaustive, so you never hand-review a diff. Also covers merge-base correctness (the single biggest lever), merge-not-rebase, `rerere`, the nub delta inventory that must survive, and the nub-side breaks upstream feature-gating causes. Supersedes the older `aube-sync` skill.
- ▌ CI Triage · nubjsFind and diagnose RED CI with the gh CLI — answer "is anything failing?" and "why?" correctly, without being handed a URL. Invoke (via the Skill tool) whenever you need to check whether a branch, commit, or PR is green, whenever someone reports failing CI, before cutting a release, and before claiming any commit is green. THE FAILURE THIS SKILL EXISTS TO PREVENT: `gh run list` reports a RUN-level `conclusion`, and a run whose rollup is `cancelled` can contain a job whose conclusion is `failure` — so filtering runs on `conclusion=="failure"` silently misses real red, and taking the latest run per workflow hides an older failed run on the same SHA. The authoritative instrument is the commit's CHECK-RUNS, which is what the GitHub UI renders. Pairs with `ci-watch` (blocking until a run is terminal) and `ci-adhoc-test` (running a probe on a real OS).
- ▌
- ▌ Nub Charts · nubjs bundleBuild a performance chart for nubjs.com — the SVG bar figures in blog posts, docs pages and social posts (a runtime augmentation against plain node, an install or dispatch comparison, a cross-tool ranking). Use whenever asked for a graphic, chart, graph or figure showing a benchmark result, whenever adding a measured claim to a docs or blog page that deserves a picture, and whenever regenerating an existing figure with fresh numbers. Covers the house visual system (720px, the light/dark/opaque triple, the Nub palette and type), the three chart forms and which one fits, the Figure wiring and the alt/caption conventions, the benchmark provenance the numbers must have, and the layout traps that only show up once the SVG is rasterized.
- ▌ Rust Build · nubjsUse when building or testing the nub Rust workspace inside a git worktree — `cargo build`/`test`/`clippy` for nub-cli/nub-core/aube in a worktree off origin/main. Explains how worktrees share ONE cargo target dir for fast incremental builds, the cross-worktree artifact-contamination hazard that sharing creates (the phantom `E0063: missing field` on correct source), and the wrapper (`scripts/rust-build.sh`) that shares by default and auto-isolates the moment a worktree diverges a depended-on crate or `runtime/`. Auto-triggers on a spurious cargo compile error that names a field/symbol absent from your checkout, on "worktree build contamination", and on setting CARGO_TARGET_DIR for a worktree.
- ▌ Ad Hoc Test · nubjsVerify new nub functionality end-to-end by building the dev binary and exercising it against real throwaway fixtures. Invoke (via the Skill tool) in BOTH directions, and the second is the one that gets skipped. (1) CONFIRM — after implementing or changing a subcommand/flag/behavior, check the feature ACTUALLY works, not just that tests pass. (2) FALSIFY — before opening a PR on behavior, and again before calling a review round done, SELF-REVIEW by sweeping many adversarial fixtures for what the change BROKE somewhere you were not looking: boundary abuse, real installed registry packages, monorepo and symlink layouts, the tier x module-format matrix. Green gates plus a working reported-case is NOT that sweep. Reviewers read code and cannot run it, so they systematically miss the silent wrong answer — the resolution that returns a different module with no error — which only a fixture run can catch, by checking WHICH file answered rather than that something did. The loop: create fixtures in a tmp dir, build the
- ▌ Plan Thread · nubjsUse when an effort's APPROACH isn't settled yet and needs collaborative design BEFORE implementation — fleshing out how a feature/change should work, weighing options, resolving open questions with the human. The design-in-progress thread profile. Auto-triggers on "spin up a plan", "let's design", "plan thread", "how should we approach", "think through the approach".
- ▌ Audit Thread · nubjsUse when running a compatibility/parity AUDIT — enumerating where nub diverges from a reference it claims parity with (pnpm CLI grammar, a lockfile format, a Node behavior, a flag surface). Encodes the hard gates that stop an audit from surfacing false positives. Auto-triggers on "audit", "compat audit", "parity audit", "find all the gaps", "what are we missing vs <tool>".
- ▌
- ▌
- ▌
- ▌ Remote Build · nubjsRun a nub Rust build, clippy gate, test suite, or ad-hoc fixture script on an ephemeral Google Cloud spot VM instead of the dev Mac. Invoke (via the Skill tool) whenever you are about to start a COLD build, `cargo clippy --all-targets --all-features`, a full `cargo test`, a `release` build, or a fixture sweep that needs no macOS-specific behavior. THE RULE THIS SKILL EXISTS TO CARRY: the VM is the DEFAULT for all of those — not a contention fallback — and only the ~5s warm incremental loop and macOS-native checks stay local, because remote loses exactly those two. Also the go-to when someone asks to "build this without hammering my machine" or to reclaim CPU from builds. For a macOS binary use scripts/mac-build.ts (a real macOS runner), never a cross-compile. Pairs with `dev-loop` (the local loop), `rust-build` (target-dir sharing), `rust-build-hygiene` (not orphaning builds), `ad-hoc-test` (what to put in an adhoc script), `cpu-reduction` (clearing residue that already accumulated), and `gcloud-vm` (the unde
- ▌ Address Issue · nubjsEnd-to-end playbook for working a GitHub issue (or bug-fix PR) on nubjs/nub: triage → acknowledge an external report with an "Investigating" comment → reproduce it yourself → SIZE it → fix it at that size (most issues are a small fix you just write — no investigation spike, no sub-agent fleet, no top-tier model) → open a PR that references the issue with `Closes #N` → on merge, comment the resolution → on release, comment the version + release link. Invoke (via the Skill tool) whenever you pick up an issue to work, or are asked to fix a reported bug. Encodes both the maintainer-hygiene conventions in AGENTS.md (so the reporter is acknowledged, the issue auto-closes on merge, and the loop closes when the fix ships) and the proportionality gate that keeps an ordinary bug from being worked like an audit.
- ▌
- ▌ CI Adhoc Test · nubjsRun ad-hoc / exploratory tests on a real OS or platform via CI when the behavior CANNOT be reproduced on the local host or in Docker — macOS Seatbelt / sandbox-exec / codesigning, Windows cmd.exe / --script-shell shell selection / .cmd resolution / Authenticode, musl-vs-glibc, Linux-arm64, a specific Node floor. Invoke (via the Skill tool) whenever the user asks to "test this on macOS/Windows CI", "probe this across operating systems / platforms", "run an ad-hoc cross-platform check", or any validation that needs a real macOS or Windows runner. THE KEY FACT this skill exists to carry: a pull request is NOT required — a branch-scoped GitHub Actions workflow (workflow_dispatch + push to the branch) runs the probe with no PR open. Pairs with `ad-hoc-test` (local host probing), `dev-loop` (build), `ci-watch` (await the run), and AGENTS.md's Docker section (Linux-only; this skill covers what Docker can't).
- ▌ Cpu Reduction · nubjs bundleDiagnose and clear CPU, memory, and disk contention on the maintainer's dev host. Invoke when the machine is slow, load or swap is high, disk is filling, a Rust build hangs on a target lock, a benchmark needs a quiet host, stale worktree targets have accumulated, or orphaned build/test processes are suspected. Covers safe worktree-target cleanup, detached Rust builds, orphaned Node tests and synthetic load generators, the preserve list, and the measure-to-verify loop. For preventing orphan builds, use `rust-build-hygiene`.
- ▌ Linux Vm Test · nubjs bundleRun ad-hoc Nub tests and debugging probes on real local Linux guests. Use for Linux-specific sandbox, kernel, distro, architecture, package, or runtime behavior that Docker cannot reproduce faithfully. Selects persistent Lima for source-mounted iteration or ephemeral Tart for clean-image reproduction.
- ▌ Visual Review · nubjs bundleVerify UI/layout/styling changes are correct by computing occlusion, clipping, and alignment from the browser's resolved paint order via the chrome-devtools MCP `evaluate_script` tool — instead of eyeballing a flat screenshot. Invoke BEFORE declaring any UI, site, or styling/layout change correct. Screenshots have no depth buffer, so z-index/occlusion/clip bugs are exactly where "just look at it" fails; the `evaluate_script` routines below turn those fuzzy visual judgments into deterministic measurements — including optical center-of-mass, which measures the glyph ink's true visual center so differently-sized labels can be aligned by more than eye.
- ▌ Disk Reduction · nubjs bundleReclaim disk on the maintainer's Mac when the volume is full or filling — ENOSPC, "no space left on device", a failed build or agent harness, or a routine sweep of Rust build residue. Invoke whenever free space is the problem. Covers the two families that actually hold the space (worktree-private `target/` dirs and orphaned content-hashed shared-target buckets under `~/.cache/nub`), the safety gates that keep a live bucket and the installed `nub-dev` binary alive, and why `du` and `df` disagree by tens of GB on APFS. For CPU load, orphaned processes, or a build hung on a target lock, use `cpu-reduction`; for not creating the residue, `rust-build-hygiene`.
- ▌ Download Stats · nubjsGenerate download-stats CSVs and a chart for nub across its distribution channels (npm + GitHub release assets, which subsume Homebrew). Invoke (via the Skill tool) when asked to check, chart, or export download numbers, install counts, or adoption stats. Encodes the channel map, which numbers may be added together, each channel's real granularity and lag, and the checksum-asset inflation gotcha.
- ▌ Pm Perf Tracing · nubjsPerformance-trace Nub package-manager installs using the existing phase timings, structured diagnostics, and sampling-profiler workflow. Use when an install or package-manager operation is unexpectedly slow and the bottleneck needs to be localized before changing code.
- ▌ Probe Platforms · nubjsBring a test harness or probe up on a NEW operating system (Windows or Linux), or debug one that fails there. Invoke before the first run on a platform, and whenever a harness works on one OS but not another. Carries the bring-up ladder that avoids spending hours learning single booleans, the Windows spawn/path/disk faults that each present as something else entirely, the Linux Landlock and node-layout traps, and the remote-shell mechanics (PowerShell-over-SSH quoting, pkill matching your own command) that waste a loop each time they are rediscovered.
- ▌ Research Thread · nubjsUse when the deliverable is a FACT — not code, not a design, not a gap catalog. A prior-art survey, "how has X already been solved", "what did they try and abandon", a long empirical sweep, or any non-trivial question whose answer will be cited for months. Produces a living write-up at `wiki/research/<topic>.md`. Auto-triggers on "research this", "prior art", "survey", "find out how X works", "what's the state of the art", "dig into whether".
- ▌ Windows Vm Test · nubjs bundleRun ad-hoc Nub tests and debugging probes in the maintainer's existing local Windows 11 ARM64 QEMU/HVF VM when its external disk and runbook are present. Use for interactive win32-arm64 or Windows-on-ARM x64-emulation checks; use ci-adhoc-test for true x64-native behavior or when the local VM is unavailable.
- ▌
- ▌ Type Declarations · nubjsAdd, audit, or update @nubjs/types declarations for Nub runtime APIs. Use whenever Nub adds or changes a user-visible global, built-in method, module loader type, or TC39 proposal; when TypeScript or @types/node gains an overlapping declaration; and before every release to reconcile runtime changes since the previous tag. Covers conflict-safe global augmentation, compiler-version routing, fixture matrices, and package verification.
- ▌ Rust Build Hygiene · nubjsBest practices for spinning up nub Rust builds so they are PERFORMANT and CLEAN THEMSELVES UP — the prevention side of the recurring orphaned-build problem on the maintainer's dev host. Invoke (via the Skill tool) before launching any `cargo build`/`test`/`clippy` you might background or leave running, when setting up a build in a sub-agent, or when deciding how to wait on a long build. Encodes the ONE rule that stops the bleeding — never DETACH a build (setsid/nohup/`& disown` reparent it to PID 1, it outlives its launcher, holds the target-dir lock for 30+ min, and `TaskStop` does NOT reap it) — plus how to background correctly (harness-tracked), how to wait on a long build (a sub-agent that owns the wait, never a detached shell), one-target-per- concurrent-build, the fast profile + QoS clamp, and cleanup-on-done. For clearing residue that already accumulated, see `cpu-reduction`; for the target- dir sharing/isolation decision, see `rust-build`; for the worktree loop, `dev-loop`.
- ▌ Implementation Thread · nubjsTake a single task or issue through the COMPLETE engineering workup — grill the brief with the human → plan → review the plan → implement → review the implementation (multi-lens where the blast radius warrants) → open a PR → await CI → fix CI → check for and integrate external reviews → RETURN CONTROL before merge. Invoke (via the Skill tool) whenever the user says "implementation-thread", or asks to drive a task/issue all the way through to a held PR. The defining shape: the effort is owned end-to-end by ONE sub-agent (an L1) that spawns its OWN L2 sub-agents for design and multi-lens review, carries continuity across phases, and PAUSES — comes to rest to surface a question UP — whenever a decision the human owns arises. It opens by loading the `grilling` skill and running its round-based INTERVIEW whenever the change writes substantial new code, so the human settles the design tree before a line of it exists. It returns control to the orchestrator BEFORE merging unless explicitly told "merge it" / "all the