agentleFS
codervisorcodervisor/lean-spec/.agents/skills/leanspec-pre-push/SKILL.md

leanspec-pre-push

Skill296 starsChanged 6 months agoMITView on GitHub

Run before pushing code to the lean-spec repo to catch what reviewers and CI will catch later, and confirm the branch has a linked spec issue in a valid state. Reproduces the merge-preview environment, walks through this repo's common merge-conflict patterns, and runs the project's typecheck / clippy / test gates. Triggers include "before push", "ready to push", "pre-push check", "push readiness", "prep for PR", "resolve merge conflict", "merge conflict", "branch has conflicts", "sync with main", or proactively before any git push on a lean-spec branch.

  • Deletes or force-pushes
  • Commits and pushes

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. codervisor/leanspec★ 294100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository8 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. About 0 are common, 5 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run all of these from the repo root.

    line 22
  2. Very specific:

    Verify before committing the merge: Run pnpm typecheck && pnpm pre-push.

    line 46
  3. Very specific:

    Prefer merge over rebase for syncing main here: the branch is likely already pushed, rebase rewrites history, and force-push is a …

    line 62
  4. Very specific:

    package.json version field: never resolve by hand. Run pnpm sync-versions to re-derive from the root version.

    line 67
  5. Very specific:

    pnpm-lock.yaml: never hand-edit. After resolving the source package.json conflicts, run pnpm install to regenerate the lockfile, then git …

    line 68
  6. Very specific:

    Cargo.lock: never hand-edit. After resolving Rust Cargo.toml conflicts, run pnpm build:rust and let cargo regenerate.

    line 69
  7. Very specific:

    If the change touches the desktop bundle (packages/desktop/), also run pnpm dev:desktop smoke check.

    line 87
  8. Very specific:

    Treat any warning as a blocker.

    line 89
  9. Distinctive:

    If the diff touches user-visible strings:

    line 93
  10. Distinctive:

    If you added a new locale file, add it to whatever locale-loader registers them.

    line 97
  11. Distinctive:

    Before pushing, confirm this branch corresponds to a known spec issue (or is explicitly trivial).

    line 101
  12. Very specific:

    Find the spec issue: Search open issues with the spec label on codervisor/leanspec:

    line 103
  13. Very specific:

    If you can't find one, stop and create one via issue-spec (or triage whether this is truly trivial).

    line 111
  14. Very specific:

    Confirm any open questions on the spec are resolved: If the spec's ### Open questions subsection still has unanswered items, stop and …

    line 113
  15. Very specific:

    If the spec issue this PR closes is labeled provider-impact:

    line 139
  16. Very specific:

    If Breaking change? yes on the spec, confirm a CHANGELOG entry is staged for this PR under the next [Unreleased] heading.

    line 143
  17. Very specific:

    If the spec issue is labeled i18n:

    line 145
  18. Very specific:

    After push, open the PR with the spec-link line in its body (or apply the trivial label).

    line 157
  19. Distinctive:

    If nothing under tracked source paths changed (e.g.

    line 161

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “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

leanspec-pre-push

Mechanical checklist that catches the reviewer / CI failures this repo has actually had, plus a spec-link check that enforces the SDD loop locally.

This is lean-spec's analogue of onsager-pre-push / duhem-pre-push. The discipline is the same; the toolchain checks are lean-spec's (pnpm + cargo). The repo-specific patterns below come from this monorepo's structure (TypeScript packages, Rust crates, i18n locale files, schemas).

Why

CI on pull_request checks out a merge of origin/main + the PR branch, not the branch alone. Local pnpm typecheck without that merge is insufficient.

The spec-link step enforces "no PR without a spec or a trivial label" at push time, before the PR is open — so the author sees the problem locally instead of hearing about it from a reviewer.

Steps

Run all of these from the repo root.

1. Sync main into the branch

git fetch origin main
git merge origin/main --no-edit

Resolve conflicts locally, before push — never on the PR "Resolve conflicts" web editor (it bypasses any local validation). If the merge aborts cleanly, skip to step 2.

Resolving conflicts

  1. Inventory what conflicted:

    git status --short                   # U* lines = unresolved paths
    git diff --name-only --diff-filter=U
  2. Work by pattern, not by file. A single logical conflict often spans several files. Match what you see against the patterns below before touching conflict markers — the right fix is often "take main's version and re-apply your change on top", not a line-by-line merge.
  3. Resolve, then stage each resolved path with git add <path>. Re-run git status until no U* entries remain.
  4. Verify before committing the merge. Run pnpm typecheck && pnpm pre-push. Run pnpm test for the affected packages. If the merge touched Rust, also run pnpm build:rust and pnpm test:rust.
  5. Only then:

    git commit --no-edit                 # default "Merge branch 'main' ..." message
  6. If you get lost, bail and retry:

    git merge --abort

    This restores pre-merge state. Never git reset --hard or git checkout -- without confirming nothing is staged you care about — the merge carries uncommitted resolutions.

    Prefer merge over rebase for syncing main here: the branch is likely already pushed, rebase rewrites history, and force-push is a destructive action.

Common collision patterns to watch for

  • CHANGELOG.md: both branches added entries under the same [Unreleased] heading. Both should land — concatenate alphabetically by category (Added, Changed, Fixed, …).
  • package.json version field: never resolve by hand. Run pnpm sync-versions to re-derive from the root version. See leanspec-development "Publishing & Releases".
  • pnpm-lock.yaml: never hand-edit. After resolving the source package.json conflicts, run pnpm install to regenerate the lockfile, then git add pnpm-lock.yaml.
  • Cargo.lock: never hand-edit. After resolving Rust Cargo.toml conflicts, run pnpm build:rust and let cargo regenerate.
  • locales/en.json and locales/zh-CN.json: both branches added i18n keys. Both should land; verify each new key exists in both files. If one branch added a key only to en and the other added only to zh-CN, that's a process bug — fix the missing parity before committing the merge.
  • schemas/*.json: JSON schema files. Both branches added fields. Merge by key; verify the schema still validates by running the validator (when wired) or pnpm typecheck to confirm the generated TypeScript types still compile.
  • Generated packages/**/dist/: don't merge. Delete the conflict and rerun pnpm build.
  • specs/ legacy directory: don't author new files here post-migration. If a conflict exists in specs/ because both branches added a new specs/NNN-slug/, the correct fix is usually to delete both new directories and migrate them to GitHub issues via issue-spec. If they pre-date migration, take both arms.

2. Build / typecheck / test

Run, in order:

pnpm typecheck             # mandatory before marking work complete
pnpm pre-push              # typecheck + clippy
pnpm test                  # full Vitest suite
pnpm format:rust:check     # if Rust changed
pnpm test:rust             # if Rust changed

If the change touches the desktop bundle (packages/desktop/), also run pnpm dev:desktop smoke check.

Treat any warning as a blocker. Do not #[allow(dead_code)], #[allow(unused)], or @ts-ignore your way past it; fix the root cause. Rust clippy is -D warnings — warnings are errors.

3. i18n parity check

If the diff touches user-visible strings:

  1. Locale files live under locales/en.json and locales/zh-CN.json (and any per-package equivalents — see I18N.md).
  2. For every key added in en.json, confirm the same key exists in zh-CN.json. Translation can be a placeholder + a // TODO(i18n) comment, but the key must exist — CI will fail if zh-CN is missing keys.
  3. If you added a new locale file, add it to whatever locale-loader registers them.

4. Spec-issue link check

Before pushing, confirm this branch corresponds to a known spec issue (or is explicitly trivial). This is the local enforcement of the SDD loop's spec-link rule.

  1. Find the spec issue. Search open issues with the spec label on codervisor/leanspec:

    mcp__github__list_issues  repo=codervisor/leanspec  labels=[spec]  state=open

    Or read your commit messages (git log origin/main..HEAD) for a #N reference.

    If you can't find one, stop and create one via issue-spec (or triage whether this is truly trivial).

  2. Confirm any open questions on the spec are resolved. If the spec's ### Open questions subsection still has unanswered items, stop and resolve them in the issue thread first — the design isn't pinned yet.
  3. Draft the PR body linking line so you can paste it in:

    • Closes #N if this PR delivers the full spec.
    • Part of #N if it's one slice of a multi-PR spec.
    • Fixes #N for a defect referenced by a bug spec.

    Also draft a ## Delivers subsection listing the exact Plan items you tick with this PR.

  4. Scan the branch's commit messages for implicit issue references (advisory, not blocking):

    git log --format='%s%n%b' origin/main..HEAD | grep -oE '#[0-9]+' | sort -u

    For each #N returned, decide deliberately:

    • PR delivers that issue's acceptance → add Closes #N to the body. Multi-issue Closes lines are fine (Closes #27, Closes #30, Closes #33). Auto-close doesn't fire for issues that are only mentioned in commit subjects — without an explicit Closes line, those issues stay open after merge.
    • PR only touches that issue → use Refs #N so it cross-links without claiming closure.
    • False positive (issue number inside a code identifier, commit hash, etc.) → ignore.
  5. If this is genuinely trivial (typo, doc-only, one-line obvious fix), skip the spec-link substeps above and plan to apply the trivial label to the PR immediately after mcp__github__create_pull_request.

5. Provider-impact and i18n evidence check

If the spec issue this PR closes is labeled provider-impact:

  • Confirm ## Provider impact is filled in on the spec.
  • Confirm the PR body mirrors the relevant subset.
  • If Breaking change? yes on the spec, confirm a CHANGELOG entry is staged for this PR under the next [Unreleased] heading. See leanspec-development "Changelog".

If the spec issue is labeled i18n:

  • Confirm both locales/en.json and locales/zh-CN.json (and any per-package locale files) contain the new keys.

6. Push

git push -u origin <branch>

Retry up to 4 times with exponential backoff (2s, 4s, 8s, 16s) on transient network errors. Never use --force on main or long-lived branches without explicit ask.

After push, open the PR with the spec-link line in its body (or apply the trivial label). The spec issue stays open until the PR closes it — no status labels to flip.

Fast path

If nothing under tracked source paths changed (e.g. docs-only edits):

  • Step 2 reduces to pnpm typecheck if any docs touch typed config; otherwise it's a no-op.
  • Step 1 (sync main) is not skippable — main may have moved.
  • Step 4 (spec-link) is not skippable for non-trivial PRs.

What this skill does NOT cover

  • Writing the spec issue — see issue-spec (installed globally from onsager-ai/dev-skills).
  • Opening or managing the PR — see leanspec-pr-lifecycle.
  • The end-to-end dev loop — see leanspec-dev-process.
  • Commands, CI workflows, publishing pipelines — see leanspec-development.
  • GitHub CLI in cloud sessions — see github-integration (installed globally from onsager-ai/dev-skills).

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.