agentleFS
eric-cieloeric-cielo/moflo/.claude/skills/publish/SKILL.md

publish

Skill19 starsChanged 3 months agoMITView on GitHub

Bump version, build, test, publish to npm, and install locally

  • Reads credentials
  • Installs packages
  • Commits and pushes

66 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create, render and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    create

    Also in 4 projects that use this

  • suxrobGMSkill

    render

    Generate raster images (PNG, JPEG, WebP) from natural language prompts using Python rendering engines. Covers graphics, charts, layouts, and procedural art. Not for SVG output.

    Also in 3 projects that use this

  • JaimeGBASkill

    ingest

    Digest an external source (article, paper, transcript, URL, book chapter) and integrate its content into the knowledge base

    Also in 6 projects that use this

  • genomewalkerSkill

    explore

    RLM-style recursive memory exploration - dynamically navigate the memory graph

    Also in 4 projects that use this

  • GoogleSkill

    translate

    Translates a common phrase into one or more languages.

    Also in 3 projects that use this

  • VercelSkill

    setup

    Set up Vercel CLI and project configuration. Use when the user says "set up Vercel", "configure Vercel", "link to Vercel", or "vercel init".

    Also in 14 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. 0 are common, 8 are distinctive, and 12 are very specific to this project.

  • 0

    Common

    Most of the 55 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Default bump type is patch if not specified

    line 40
  2. Very specific:

    Without -rc: Use npm version <patch|minor|major> --no-git-tag-version

    line 44
  3. Very specific:

    If current version is already an RC of the same bump level (e.g., 4.8.57-rc.3), increment the RC number (→ 4.8.57-rc.4)

    line 46
  4. Very specific:

    Always runs regardless of CHECK_MODE.

    line 74
  5. Distinctive:

    Must exit 0: If it fails, stop and fix the build error.

    line 76
  6. Distinctive:

    Must have 0 test file failures: If any test files fail, retest them individually to distinguish real failures from flaky ones (per broken …

    line 94
  7. Distinctive:

    Read the fingerprint output from Step 1.

    line 117
  8. Very specific:

    If CHECK_MODE=true, walk all manual gates regardless of triggers (full audit).

    line 131
  9. Very specific:

    If the trigger set is none AND CHECK_MODE=false: skip Step 7 entirely.

    line 133
  10. Distinctive:

    Commit the version bump files:

    line 137
  11. Distinctive:

    Only commit version-related files.

    line 145
  12. Very specific:

    If 401 or "not logged in": auth token in ~/.npmrc is missing or expired.

    line 250
  13. Very specific:

    Verify with npm whoami before proceeding.

    line 264
  14. Distinctive:

    If npm returns an OTP/one-time-password error, ask the user for their authenticator code

    line 276
  15. Very specific:

    If package.json or package-lock.json changed from the install:

    line 305
  16. Distinctive:

    All commands run from the project root — never cd into subdirectories

    line 338
  17. Very specific:

    Never use --force on npm publish

    line 339
  18. Very specific:

    Never install moflo globally — it is always a local devDependency

    line 340
  19. Distinctive:

    If any step that DID run fails, stop and fix the issue before proceeding — do not skip steps

    line 341
  20. Very specific:

    Use --check / -ch when:

    line 347

“Common” is measured: kept by at least 6 in 10 of the 55 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/publish - Version Bump, Build, Test & Publish

Automated release pipeline for moflo. Bumps version, commits, builds, tests, runs doctor, publishes to npm, and installs the new version locally.

Arguments: $ARGUMENTS

Usage

/publish              # patch bump, default mode (skips CI-covered gates)
/publish minor        # minor bump (4.8.56 → 4.9.0)
/publish major        # major bump (4.8.56 → 5.0.0)
/publish -rc          # patch RC bump (4.8.56 → 4.8.57-rc.1)
/publish minor -rc    # minor RC bump (4.8.56 → 4.9.0-rc.1)
/publish --check      # full pre-flight (lint + test + smoke + everything)
/publish -ch          # short form of --check
/publish minor -ch    # combine: full pre-flight on a minor bump

--check / -ch flag (presence-only)

Default (flag absent): runs build + doctor + trigger-based manual checks only. Skips local lint/test/smoke because lint+test are covered by ci.yml on every PR + push to main, and cross-platform smoke is dispatched as part of this skill (Step 8.5 below) — the release-smoke.yml workflow runs the full 3-OS matrix on the exact commit about to be published.

With --check or -ch (any presence): runs the full pre-flight from pre-publish-rules.md — lint, build, test, doctor (strict), local clean smoke, local populated smoke, and a forced full walk of every manual gate. Use this for publishes that didn't go through a green PR, risky releases, or when you want belt-and-suspenders on the local box in addition to the CI matrix.

The flag is presence-only. --check and -ch both set it to true. There is no --check=true / --check=false syntax — absence means false.


Step-by-Step Procedure

Step 0: Parse Arguments

  • Default bump type is patch if not specified
  • -rc flag: produce a release candidate
  • --check or -ch (presence): set CHECK_MODE=true. Otherwise CHECK_MODE=false.
  • Determine the new version string:
    • Without -rc: Use npm version <patch|minor|major> --no-git-tag-version
    • With -rc: Calculate manually:
      • If current version is already an RC of the same bump level (e.g., 4.8.57-rc.3), increment the RC number (→ 4.8.57-rc.4)
      • Otherwise, bump the base version and append -rc.1 (e.g., 4.8.56 → 4.8.57-rc.1)
      • Write with: npm version <new-version> --no-git-tag-version

Step 1: Compute Manual-Check Fingerprint (always)

bash .claude/skills/publish/fingerprint.sh

The script diffs HEAD against the most recent chore: install moflo@* commit and pattern-matches the file list against the manual-gate triggers from pre-publish-rules.md. Output is one block:

Triggered manual checks: bin-scriptfiles-sync info-loss-audit
Diff range: <last-publish-sha>..HEAD
Changed files: 7

Triggered manual checks: none means gates 1/2/6 don't apply to this diff — skip them entirely.

This step costs ~50 tokens and is the cornerstone of token-efficient default mode.

Step 2: Build (always)

npm run build

Always runs regardless of CHECK_MODE. Syncs the version to src/cli/version.ts via the version lifecycle script, then compiles all TypeScript. Confirms the deliverables on disk are correct.

Must exit 0. If it fails, stop and fix the build error.

Step 3: Lint (only if CHECK_MODE=true)

npm run lint

Skipped by default — ci.yml runs lint on every PR with max-warnings 0. Run when --check is set.

Step 4: Tests (only if CHECK_MODE=true)

npm test

Skipped by default — ci.yml runs the full test suite on every PR. Run when --check is set.

Must have 0 test file failures. If any test files fail, retest them individually to distinguish real failures from flaky ones (per broken window theory). Fix all real failures before proceeding.

Step 5: Doctor (always — strict, no repair)

npx moflo doctor --strict

Doctor is the only check with no CI equivalent — it inspects local state (daemon lock, embeddings hygiene, sandbox tier, vector-stats freshness) that CI cannot validate for you. Always runs in --strict mode regardless of CHECK_MODE.

Never --fix on the publish path. A release pipeline must fail fast on broken local state, not silently repair it; a doctor that auto-repairs masks the very signal we want — "something is off, stop and investigate before shipping." If doctor --strict fails, stop and run flo healer --fix (or npx moflo doctor --fix) interactively, verify the repair, then retry the publish.

Step 6: Local Smoke Tests (only if CHECK_MODE=true)

npm run test:smoke
npm run test:smoke:populated

Skipped by default. Local smoke covers the same harness as CI's Ubuntu leg, so it adds little signal over release-smoke.yml's Ubuntu matrix entry (Step 8.5). Run only when --check is set — useful if you want belt-and-suspenders on the local box before dispatching the full CI matrix.

Step 7: Manual Gate Walk (trigger-based, even in default mode)

Read the fingerprint output from Step 1.

TriggerManual check (gate)What to walk
split-newlinesGate 7Diff the changed file-reading code; verify any newline split uses /\r?\n/ not '\n'
homedir-tmpdirGate 7Verify env-var literals use os.homedir() / os.tmpdir(), not raw process.env.HOME / /tmp
bwrap-permissionsGate 7Spell bash steps that need network declare permissionLevel: elevated
posix-only-spell-bashGate 7Spell bash steps avoid mkdir/rm/cp; use node -e with fs/os for cross-platform file ops
bin-scriptfiles-syncGate 8New bin/ script appears in all three scriptFiles arrays (session-start-launcher.mjs, init/moflo-init.ts, third sync site)
helper-static-filesGate 8New helpers ship as static bin/ files, not generated at runtime
shipped-guidance-prefixGate 8New shipped guidance has moflo- prefix and lives in .claude/guidance/shipped/
files-glob-coverageGate 9Run npm pack --dry-run and confirm new shipped files appear in the tarball listing
info-loss-auditGate 10For each deleted/renamed file, audit destinations bullet-by-bullet — every piece of removed content has a home

If CHECK_MODE=true, walk all manual gates regardless of triggers (full audit). If CHECK_MODE=false, walk only triggered ones.

If the trigger set is none AND CHECK_MODE=false: skip Step 7 entirely.

Step 8: Commit & Push

Commit the version bump files:

git add package.json package-lock.json src/cli/version.ts
git commit -m "chore: bump version to <new-version>"
git push origin main

Only commit version-related files. Do not stage unrelated changes.

Step 8.5: Dispatch release-smoke and block until green

# Capture the SHA we just pushed — release-smoke runs against this exact commit.
PUBLISH_SHA=$(git rev-parse HEAD)

# Trigger the full 3-OS × 2-harness matrix. `sha` is a required workflow input
# so the dispatched run is unambiguously bound to this commit.
gh workflow run release-smoke.yml --ref main -f sha="$PUBLISH_SHA"

# Find the dispatched run, block until it finishes, then PROVE it green.
#
# `gh run watch --exit-status` is NOT the gate. It has been observed to exit 0
# while most of the matrix was still in progress (moflo@4.12.4-rc.7 publish:
# exit 0 with 7 of 9 jobs unfinished), which would publish against an unproven
# matrix. It is used here only to block cheaply — the verdict comes from an
# explicit status/conclusion read afterwards. Same rule
# `.claude/skills/fl/phases.md` Phase 5.3b already states for
# `gh pr checks --watch`: a green exit code is not proof.
#
# The run lookup retries instead of guessing a fixed delay, and matches on
# head_sha so a concurrent dispatch (a manual UI retry from another tab) can
# never be mistaken for ours — never `--limit 1` alone.
node -e '
const { execFileSync } = require("node:child_process");
const sha = process.argv[1];
const gh = (args) => execFileSync("gh", args, { encoding: "utf8" }).trim();
// Synchronous by design: this script does nothing but wait, and a blocking
// sleep keeps the control flow linear. Do not "fix" it into setTimeout.
const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
const deadline = Date.now() + 60 * 60 * 1000;
const WATCH_TIMEOUT_MS = 10 * 60 * 1000;

let runId = "";
while (!runId && Date.now() < deadline) {
  const rows = JSON.parse(gh(["run", "list", "--workflow=release-smoke.yml", "--branch", "main",
                              "--json", "databaseId,headSha"]));
  const hit = rows.find((r) => r.headSha === sha);
  if (hit) { runId = String(hit.databaseId); break; }
  sleep(5000);
}
if (!runId) {
  console.error("ERROR: no release-smoke run found for SHA " + sha +
    ". Check https://github.com/eric-cielo/moflo/actions/workflows/release-smoke.yml");
  process.exit(1);
}
console.log("release-smoke run " + runId + " bound to " + sha);

for (;;) {
  // Blocks while the run is live; may also return early and prematurely green.
  // Capped so a stalled watch cannot outlive the deadline below — on timeout we
  // simply fall through to the authoritative status read and watch again.
  try {
    execFileSync("gh", ["run", "watch", runId, "--exit-status"],
                 { stdio: "inherit", timeout: WATCH_TIMEOUT_MS });
  } catch (err) {
    // Expected when the run failed (watch exits non-zero) or when the cap above
    // fired. Surfaced rather than swallowed so a real fault — gh missing, auth
    // expired, rate limit — is visible instead of looking like a slow run.
    console.error("gh run watch: " + ((err && err.message) || err));
  }
  const state = JSON.parse(gh(["run", "view", runId, "--json", "status,conclusion"]));
  if (state.status === "completed") {
    if (state.conclusion !== "success") {
      console.error("ERROR: release-smoke concluded " + state.conclusion +
        " — inspect: gh run view " + runId + " --log-failed");
      process.exit(1);
    }
    break;
  }
  if (Date.now() > deadline) {
    console.error("ERROR: release-smoke still " + state.status + " after 60m — run " + runId);
    process.exit(1);
  }
  sleep(15000);
}

// Every leg, not just the rollup — a skipped or cancelled job is not a pass.
const jobs = JSON.parse(gh(["run", "view", runId, "--json", "jobs"])).jobs;
const bad = jobs.filter((j) => j.conclusion !== "success");
if (bad.length > 0) {
  console.error("ERROR: " + bad.length + " job(s) not success: " +
    bad.map((j) => j.name + "=" + (j.conclusion || "incomplete")).join(", "));
  process.exit(1);
}
console.log("release-smoke GREEN — " + jobs.length + " jobs, run " + runId);
' "$PUBLISH_SHA"

release-smoke.yml runs full consumer + populated smoke on Ubuntu/macOS/Windows, plus file-sync smoke on all three filesystems. Per-PR CI is intentionally Ubuntu-only to keep recurring cost manageable — the full cross-platform matrix is paid once here, at publish time, against the exact commit we're about to publish.

Wall time expectations: typical run is ~15-20 min once caches are warm. The first dispatch after release-smoke.yml lands will have cold caches on every leg (no prior runs of this workflow exist to populate the consumer-warm and fastembed caches per-OS). Expect ~25-35 min on that first dispatch — the macOS leg is the long pole. Subsequent dispatches reuse the cache and settle to the typical ~15 min.

Never publish on gh run watch's exit code alone. The block above treats it as a cheap way to block, not as the verdict — it can return 0 with the matrix still running. The gate is the explicit status == "completed" + conclusion == "success" read, plus a per-job sweep so a cancelled or skipped leg cannot pass as green.

If the block above exits non-zero: stop immediately. It prints the run id and, on a real failure, the conclusion. Inspect the failed leg with gh run view <run-id> --log-failed, fix the underlying issue, push the fix, then re-run this step (no need to rerun Steps 0–8 — the bump commit is already on main, and the SHA-filtered lookup will pick up the new dispatched run against the same SHA only after cancel-in-progress: false lets the previous run drain). Do not proceed to npm publish until release-smoke is green for the SHA you intend to publish.

Step 9: Verify npm Authentication

npm whoami

If 401 or "not logged in": auth token in ~/.npmrc is missing or expired. Ask the user for a valid npm publish token.

How to create a token (provide these instructions to the user if needed):

  1. Go to https://www.npmjs.com/settings/~/tokens
  2. Click "Generate New Token" → select "Granular Access Token"
  3. Set permissions: "Read and write" for the moflo package
  4. Copy the token (starts with npm_...)

Once the user provides the token, write it to ~/.npmrc:

echo "//registry.npmjs.org/:_authToken=<token>" > ~/.npmrc

Verify with npm whoami before proceeding.

Step 10: Publish to npm

npm publish --tag <tag>
  • For stable releases: npm publish (publishes to latest tag by default)
  • For RC releases: npm publish --tag rc (publishes to rc tag so it doesn't become latest)

OTP handling:

  • If npm returns an OTP/one-time-password error, ask the user for their authenticator code
  • Then retry with: npm publish --otp=<code> --tag <tag>
  • Tip: Granular access tokens created on npmjs.com do NOT require OTP — prefer those over legacy tokens

Step 11: Verify Publication

npm view moflo version
npm view moflo dist-tags

Confirm the published version matches what we just built.

Step 12: Install Locally

npm install moflo@<new-version> --save-dev
npm install --package-lock-only --force
npm ci --dry-run --legacy-peer-deps

The first command updates package.json and package-lock.json to use the newly published version as a devDependency.

The second command (--package-lock-only --force) backfills cross-platform optional-dependency entries that npm omits from the lockfile when npm install runs on a single host platform. Without it, transitive optional deps like the nested @rolldown/binding-wasm32-wasi/node_modules/@emnapi/* entries get dropped when publishing from Windows, and the resulting lockfile fails npm ci on Ubuntu/macOS CI legs. This produced the green-release-smoke → red-ci.yml divergence in run 26487580745 (moflo@4.10.27 install commit).

The final npm ci --dry-run --legacy-peer-deps proves the resulting lockfile is in sync with package.json before we commit it. If this exits non-zero, stop and investigate — do not commit a broken lockfile.

Step 13: Final Commit

If package.json or package-lock.json changed from the install:

git add package.json package-lock.json
git commit -m "chore: install moflo@<new-version>"
git push origin main

The chore: install moflo@<version> commit message is the anchor the fingerprint uses to bound future diffs — keep the prefix exact.

Output

Print a summary at the end:

Publish Summary
───────────────
Mode:            default | --check
Version:         <old> → <new>
Tag:             latest | rc
Build:           passed
Tests:           skipped (CI-covered) | <N> files passed, <N> tests passed
Lint:            skipped (CI-covered) | passed
Doctor:          <N> passed, <N> warnings
Smoke (local):   skipped (CI-covered) | passed
Release-smoke:   green (run <id>, 3-OS × 2-harness)
Triggered gates: <list> | none
Published:       moflo@<new-version>
Installed:       moflo@<new-version> (devDependency)

Important

  • All commands run from the project root — never cd into subdirectories
  • Never use --force on npm publish
  • Never install moflo globally — it is always a local devDependency
  • If any step that DID run fails, stop and fix the issue before proceeding — do not skip steps
  • The prepublishOnly script in package.json runs npm run build automatically, so npm publish will fail-fast on any TypeScript or asset-bundling error even if Step 2 had been skipped (it isn't — Step 2 always runs)
  • Pre-publish rules live in .claude/guidance/internal/pre-publish-rules.md — never duplicate or paraphrase them in this skill; reference and follow

When to use --check

Use --check / -ch when:

  • The PR didn't go through CI (e.g., publishing from a local-only branch)
  • You're publishing a risky change (broad refactor, infrastructure surface, packaging changes)
  • CI was red on something orthogonal you waived, and you want belt-and-suspenders locally
  • You explicitly want to re-walk gates 7/8/10 manually regardless of trigger output

For the common case — publishing right after a merged green PR — the default mode is correct and meaningfully cheaper in tokens and time.

See Also

  • .claude/skills/publish/fingerprint.sh — Trigger-fingerprint script invoked by Step 1
  • .claude/guidance/internal/pre-publish-rules.md — Authoritative gate ruleset (gates 1–10) and trigger map
  • docs/BUILD.md — Step-by-step build/publish process this skill mirrors
  • .claude/guidance/internal/dogfooding.md — Why we catch consumer-facing regressions first as our own dependency
  • harness/consumer-smoke/README.md — Smoke harness profiles (clean + populated) that prove a consumer install works
  • .github/workflows/ci.yml — Lint/build/test gates this skill skips by default (ubuntu-only)
  • .github/workflows/consumer-install-smoke.yml — Per-PR ubuntu-only smoke
  • .github/workflows/file-sync-smoke.yml — Per-PR ubuntu-only file-sync smoke
  • .github/workflows/release-smoke.yml — Full 3-OS × 2-harness matrix this skill dispatches at Step 8.5

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.